README

A PHP library to control and read information from a Daikin air conditioner over the local network through its built-in Wi-Fi HTTP API.

Requirements
Installation
Overview
Enums
Basic usage
Controlling the unit
Reading typed information
Discovering units on the network
Error handling
Changelog
License

Requirements

PHP 8.5 or higher
A Daikin air conditioner reachable on your local network (you must know its IP address)

Installation

Install the library with Composer:

composer require daikin/api

Overview

The library exposes a small set of classes that map directly to the Daikin HTTP endpoints:

Connect — handles the HTTP communication with the air conditioner. It validates the IP address and performs the GET/POST requests.
GetBasicInformation — returns basic device information (firmware, name, MAC address, etc.).
GetRemoteMethod — returns the remote control configuration of the device.
GetAirconModelInfo — returns the model information of the unit.
GetAirconSensorInfo — returns the current sensor readings (indoor/outdoor temperature, humidity, etc.).
GetAirconControlInfo — returns the current control settings (power, mode, target temperature, fan rate, fan direction, per-mode memories).
SendAirconControlInfo — sends control commands to the unit (power, mode, target temperature, fan rate, fan direction).

On top of these, Aircon provides a typed, high-level API: ControlState to change one setting at a time (see Controlling the unit), SensorInfo and BasicInfo to read typed values (see Reading typed information).

All "Get*" classes implement Daikin\Interfaces\PresentationInterface and expose a format() method that returns the data as an associative array. SendAirconControlInfo implements Daikin\Interfaces\PushInterface and exposes a push(array $parameters) method.

Any communication error throws a Daikin\Exceptions\DaikinException: invalid IP, unreachable device, non-200 HTTP response, or a request rejected by the device (the unit answers HTTP 200 with ret=PARAM NG / ret=NG instead of ret=OK).

Enums

The library ships with PHP enums to avoid using magic values when sending control commands:

Daikin\Enums\Power — ON, OFF
Daikin\Enums\Mode — AUTO, DEHUMIDIFIER, COLD, HOT, FAN. Use Mode::fromDevice($value) to map a mode read from the unit: auto is reported as 0, 1 or 7 depending on the model.
Daikin\Enums\FanRate — AUTO, SILENCE, LVL_1 to LVL_5
Daikin\Enums\FanDirection — ALL_WING_STOPPED, VERTICAL_WINGS_MOTION, HORIZONTAL_WINGS_MOTION, VERTICAL_AND_HORIZONTAL_WINGS_MOTION
Daikin\Enums\Led — ON, OFF
Daikin\Enums\EquipmentStatus

Basic usage

<?php
require_once('vendor/autoload.php');

use Daikin\SendAirconControlInfo;
use Daikin\Connect;
use Daikin\Enums\Mode;
use Daikin\GetAirconModelInfo;
use Daikin\GetBasicInformation;
use Daikin\GetRemoteMethod;
use Daikin\GetAirconSensorInfo;
use Daikin\Enums\Power;
use Daikin\Enums\FanRate;
use Daikin\Enums\FanDirection;

// Create a Connect instance with the IP address of your Daikin unit.
// An invalid IP throws Daikin\Exceptions\DaikinException.
$connect = new Connect('192.168.1.117');

// Read information from the unit. Each format() call performs an HTTP request
// and returns an associative array parsed from the device response.
var_dump((new GetBasicInformation($connect))->format());
var_dump((new GetRemoteMethod($connect))->format());
var_dump((new GetAirconModelInfo($connect))->format());
var_dump((new GetAirconSensorInfo($connect))->format());

// Send a control command to the unit.
// All values must be strings because they are sent as query parameters.
//   pow    : Power on/off
//   mode   : operating mode (cold, hot, auto, fan, dehumidifier)
//   stemp  : target temperature in Celsius
//   shum   : target humidity (0 if not applicable)
//   f_rate : fan speed
//   f_dir  : fan/wings direction
var_dump((new SendAirconControlInfo($connect))->push([
     'pow' => (string) Power::OFF->value,
     'mode' => Mode::COLD->value,
     'stemp' => '20',
     'shum' => '0',
     'f_rate' => FanRate::SILENCE->value,
     'f_dir' => (string) FanDirection::ALL_WING_STOPPED->value,
]));

Controlling the unit

/aircon/set_control_info requires every parameter on each call (pow, mode, stemp, shum, f_rate, f_dir). Aircon takes care of it: each action reads the current state, changes only what you asked for and sends the full state back.

use Daikin\Aircon;
use Daikin\Connect;
use Daikin\ControlState;
use Daikin\Enums\FanRate;
use Daikin\Enums\Mode;
use Daikin\Enums\Power;

$aircon = new Aircon(new Connect('192.168.1.117'));

$aircon->turnOn();
$aircon->setMode(Mode::COLD);
$aircon->setTargetTemperature(22.5);
$aircon->setFanRate(FanRate::SILENCE);

// Several changes in a single request:
$aircon->update(fn (ControlState $state): ControlState => $state
    ->withPower(Power::ON)
    ->withMode(Mode::HOT)
    ->withTargetTemperature(21.0));

// Read the current state:
$state = $aircon->getState();
$state->power;                  // Power::ON
$state->mode;                   // Mode::HOT
$state->getTargetTemperature(); // 21.0, or null in modes without a target ("M", "--")

ControlState is immutable: every with*() method returns a new instance.

Mode change — the unit memorises a target temperature and humidity for each mode (dt* / dh* fields). withMode() restores them.
Temperature validation — withTargetTemperature() throws a DaikinException before anything is sent when the value is not a multiple of 0.5 or is outside the range of the current mode: 18–31 °C in AUTO, 10–31 °C in HOT, 18–33 °C in COLD, 10–41 °C otherwise.

Reading typed information

Aircon also returns typed objects instead of raw string arrays:

$sensors = $aircon->getSensorInfo();
$sensors->indoorTemperature;   // 22.5
$sensors->outdoorTemperature;  // 12.0
$sensors->indoorHumidity;      // null: no humidity sensor on this unit
$sensors->compressorFrequency; // 24.0

$device = $aircon->getBasicInfo();
$device->name;            // "Living" (decoded)
$device->macAddress;      // "A0B1C2D3E4F5"
$device->firmwareVersion; // "3.3.9" (sent as "3_3_9" by the unit)
$device->power;           // Power::ON
$device->led;             // Led::ON

Every property is nullable: it is null when the unit does not report the value or sends a placeholder such as - (for instance indoorHumidity on units without a humidity sensor). The raw arrays are still available through the format() methods of the Get* classes.

Discovering units on the network

Discovery finds the units on the local network, so you do not need to know their IP address. It broadcasts DAIKIN_UDP/common/basic_info on UDP port 30050 and collects the answers for one second.

use Daikin\Discovery;

foreach ((new Discovery())->discover() as $unit) {
    echo $unit->ip, ' ', $unit->info->name, ' ', $unit->info->macAddress, PHP_EOL;

    $unit->aircon()->turnOn();  // or $unit->connect() for the low-level classes
}

Addresses — by default, the request goes to the broadcast address of every local IPv4 interface (255.255.255.255 if none is found). Pass your own list to target a subnet or a single unit: discover(['192.168.1.255']).
Timeout — new Discovery(timeout: 3.0) waits longer for slow adapters.
Source port — requests are sent from UDP port 30000, like other Daikin clients. If that port is already used on your machine, pick another one: new Discovery(new StreamUdpTransport(sourcePort: 0)) (0 = any free port).
Units are deduplicated by MAC address. Answers without a MAC address are ignored.
A DaikinDiscoveryException is thrown when the UDP socket cannot be opened or no address can be reached.

No PHP extension is required: the transport uses PHP streams.

Error handling

Every error thrown by the library extends Daikin\Exceptions\DaikinException, so a single catch handles them all:

Exception	When	Extra information
`DaikinInvalidAddressException`	The address given to `Connect` is not a valid IP	`$address`
`DaikinDeviceUnreachableException`	Network failure (timeout, connection refused…)	`getPrevious()`: HTTP client exception
`DaikinUnexpectedStatusCodeException`	The unit answered an HTTP status other than 200	`$statusCode` (also `getCode()`)
`DaikinRequestRejectedException`	The unit answered `ret` other than `OK`	`$returnCode`, e.g. `PARAM NG`
`DaikinInvalidResponseException`	The response cannot be understood (no `ret`, missing or unknown value)	—
`DaikinInvalidParameterException`	A value is refused before sending (target temperature out of range…)	—
`DaikinDiscoveryException`	The UDP discovery cannot run (socket cannot be opened, no address reachable)	—

use Daikin\Exceptions\DaikinDeviceUnreachableException;
use Daikin\Exceptions\DaikinException;
use Daikin\Exceptions\DaikinInvalidParameterException;
use Daikin\Exceptions\DaikinRequestRejectedException;

try {
    $aircon->setTargetTemperature(22.5);
} catch (DaikinInvalidParameterException $e) {
    // Nothing was sent: the value is not valid for the current mode.
} catch (DaikinRequestRejectedException $e) {
    echo $e->returnCode; // "PARAM NG"
} catch (DaikinDeviceUnreachableException $e) {
    // The unit is offline: retry later.
} catch (DaikinException $e) {
    // Any other library error.
}

Changelog

See CHANGELOG.md, including the upgrade guide from 3.x to 4.0.

License

This library is released under the LGPL-3.0-or-later license. See the LICENCE file for details.

daikin / api

Package info

Security

Statistics