Ecovolt API - Consumer API Token Endpoints

AirconControl

Get Aircon Control by ID

GET

http://localhost:8080

/api/aircon-control/by-id/{deviceId}

Retrieves a single Aircon Control by its unique ID with full details including system, tenant, user, and room information.

Get Aircon Control by ID › path Parameters

deviceId

string · required

Get Aircon Control by ID › Responses

Aircon Control retrieved successfully

AirconControl

_id

string · required

Primary ID of the Device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceType

string · enum · required

Type of device (discriminator field)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the Device (from IoT device)

Example: 1092384701928347

deviceName

string · required

Name of the Device

Example: Living Room AC

deviceNumber

number · required

Unique device number for identification

Example: 1

onStatus

string · enum · required

Status of the Device (ON / OFF / INACTIVE / ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

location

string · required

Physical location or address where the device is installed

Example: Room 101, Building A

remarks

string · required

Remarks for the Device

batchNumber

number · required

Manufacturing batch number for tracking production groups

Example: 1

chipModel

string · enum · required

Hardware chip model identifier used in the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number currently running on the device

Example: 1.0.0

ssid

string · required

Network SSID (Wi-Fi name) that the device is connected to

Example: IoT-Network-5G

tenant

string · required

Tenant ID reference

object · required

Tagged Zone

room

string · required

Room ID reference

system

string · required

System ID reference

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

lastSeen

string · date-time · required

Last time the device was seen/reported

Example: 2021-09-01

isLocked

boolean · required

Whether the device is locked. When locked, the device on/off status cannot be toggled.

Example: false

totalEnergyUsage

number · required

Total cumulative energy usage in kWh

Example: 0

totalEnergySaved

number · required

Total energy saved through optimization in kWh

Example: 0

autoUpdateAttempts

number · required

Number of auto-update OTA attempts sent to this device

Example: 0

autoUpdateBlacklisted

boolean · required

Whether device is blacklisted from auto-updates (max retries exceeded)

Example: false

manualUpdateBlacklist

boolean · required

Whether device is manually blacklisted from auto-updates by admin

Example: false

inactivityNotificationEnabled

boolean · required

Whether inactivity notifications are enabled for this device

Default: false

isIRRemote

boolean · required

Whether this is an IR remote (true) or wired control (false)

Example: true

irType

string · enum · required

Type of IR device being controlled (AIRCON or FAN)

Enum values:

AIRCON

FAN

Example: AIRCON

Default: AIRCON

temperature

number · required

Temperature setting in degrees Celsius

Example: 24

targetState

string · enum

Pending desired on/off state commanded by backend (cloud / scheduled). Set when a toggle is issued; cleared when the device reports a matching state or a physical (MANUAL) press overrides it. Always ON or OFF when present.

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when targetState was last written. Used to expire stale SCHEDULED intents (24hr TTL). CLOUD intents do not expire.

Example: 2026-05-25T08:00:00.000Z

targetSource

string · enum

Origin of the pending targetState. Drives TTL behavior on reconcile. Only CLOUD / SCHEDULED are ever written here.

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: CLOUD

deviceModel

string

Model name or identifier of the device

Example: TP-Link HS110

deviceBrand

string

Brand or manufacturer of the device

Example: TP-Link

isSpare

boolean

Whether the device is a spare/inventory device. Spare devices can be filtered out of user-facing dashboards.

Example: false

object

Schedule configuration for the device. Contains recurring weekly schedules and one-time scheduled tasks.

realTimePower

number

Real-time power consumption in watts

Example: 1500

realTimeCurrent

number

Real-time current in amperes

Example: 6.5

lastAutoUpdateAttempt

string · date-time

Timestamp of last auto-update OTA attempt

inactivityNotificationSentAt

string · date-time

Timestamp when the last inactivity notification was sent for this device

Device[]

List of smart devices controlled by this aircon sensor

fanBrand

string · enum

Brand of the fan unit (only applicable when irType is FAN)

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Example: KDK_T60AW

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

brand

string · enum

Brand of the AC unit being controlled

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number (e.g. FTKM50QV1M). Required for consumption estimation via AirconModelSpec lookup. Stored uppercased and trimmed.

Example: FTKM50QV1M

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

temperatureMin

number

Min ambient temperature threshold in Celsius for alerts

Example: 18

temperatureMax

number

Max ambient temperature threshold in Celsius for alerts

Example: 30

humidityMin

number

Min ambient humidity threshold percentage for alerts

Example: 30

humidityMax

number

Max ambient humidity threshold percentage for alerts

Example: 80

notificationThresholdHour

number

Minimum hours between repeated notifications for the same alert type

Example: 4

Default: 4

seriesType

string · enum

Series type — NORMAL (control only) or PRO (control + ambient temp/humidity sensing)

Enum values:

MAXWELL

MAXWELL_PRO

Example: MAXWELL

Default: MAXWELL

targetTemperature

number

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: true

lastSmartModeUpdate

string · date-time

Timestamp of the last update to smart mode settings (used for tracking when thresholds were last updated)

Example: 2024-01-01T12:00:00Z

aggressiveness

number · min: 0 · max: 1

Smart mode proportional gain. Controls how aggressively the AC setpoint compensates for ambient-vs-target deviation. 0 = no compensation (setpoint equals target), 1 = full compensation, >1 = over-compensation. Default: 0.5.

Example: 0.5

Default: 0.5

deadbandTemperature

number · min: 0 · max: 3

Smart mode deadband in °C. If the ambient temperature is within this range of the target, no setpoint adjustment is sent. Prevents oscillation and unnecessary compressor cycling. Default: 0.5.

Example: 0.5

Default: 0.5

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum interval in minutes between smart mode recalculations. Prevents excessive updates. Typical values: 15, 30, 60. Default: 60.

Example: 60

Default: 60

GET/api/aircon-control/by-id/{deviceId}

curl http://localhost:8080/api/aircon-control/by-id/:deviceId

Example Responses

{
  "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
  "deviceType": "PLUG",
  "macId": "1092384701928347",
  "deviceName": "Living Room AC",
  "deviceNumber": 1,
  "onStatus": "ON",
  "targetState": "ON",
  "targetStateSetAt": "2026-05-25T08:00:00.000Z",
  "targetSource": "CLOUD",
  "location": "Room 101, Building A",
  "remarks": "remarks",
  "deviceModel": "TP-Link HS110",
  "deviceBrand": "TP-Link",
  "batchNumber": 1,
  "chipModel": "ESP32C2",
  "versionNumber": "1.0.0",
  "ssid": "IoT-Network-5G",
  "tenant": "tenant",
  "zone": {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "name": "Glenn Quah Han Rong",
    "email": "glenn@gmail.com",
    "remarks": "remarks",
    "zoneType": "LABORATORY",
    "zoneEnergyReport": "64b7f1e6f9c9d4e5b8a9f7c3",
    "tenant": "tenant",
    "rooms": [
      "64b7f1e6f9c9d4e5b8a9f7c3"
    ],
    "devices": [
      "64b7f1e6f9c9d4e5b8a9f7c3"
    ],
    "distributionBoxes": [
      "64b7f1e6f9c9d4e5b8a9f7c3"
    ],
    "floorPlanKey": "floor-plans/uuid.png",
    "floorPlanUrl": "https://cdn.ecovolt.ai/floor-plans/uuid.png",
    "floorPlan": "floorPlan"
  },
  "room": "room",
  "system": "system",
  "createdAt": "2021-09-01",
  "updatedAt": "2021-09-01",
  "lastSeen": "2021-09-01",
  "isLocked": false,
  "isSpare": false,
  "deviceSchedule": {
    "oneTimeSchedules": [
      {
        "dateTime": "2023-10-31T06:00:00Z",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "monday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "tuesday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "wednesday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "thursday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "friday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "saturday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "sunday": [
      {
        "time": "06:00",
        "action": "OFF",
        "actionValue": 24,
        "ruleName": "ruleName"
      }
    ],
    "confirmationState": "PENDING"
  },
  "realTimePower": 1500,
  "realTimeCurrent": 6.5,
  "totalEnergyUsage": 0,
  "totalEnergySaved": 0,
  "autoUpdateAttempts": 0,
  "autoUpdateBlacklisted": false,
  "manualUpdateBlacklist": false,
  "lastAutoUpdateAttempt": "2024-08-25T15:00:00Z",
  "inactivityNotificationEnabled": false,
  "inactivityNotificationSentAt": "2024-08-25T15:00:00Z",
  "smartDevices": [
    {
      "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
      "deviceType": "PLUG",
      "macId": "1092384701928347",
      "deviceName": "Living Room AC",
      "deviceNumber": 1,
      "onStatus": "ON",
      "targetState": "ON",
      "targetStateSetAt": "2026-05-25T08:00:00.000Z",
      "targetSource": "CLOUD",
      "location": "Room 101, Building A",
      "remarks": "remarks",
      "deviceModel": "TP-Link HS110",
      "deviceBrand": "TP-Link",
      "batchNumber": 1,
      "chipModel": "ESP32C2",
      "versionNumber": "1.0.0",
      "ssid": "IoT-Network-5G",
      "tenant": "tenant",
      "zone": {
        "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
        "name": "Glenn Quah Han Rong",
        "email": "glenn@gmail.com",
        "remarks": "remarks",
        "zoneType": "LABORATORY",
        "zoneEnergyReport": "64b7f1e6f9c9d4e5b8a9f7c3",
        "tenant": "tenant",
        "rooms": [
          "64b7f1e6f9c9d4e5b8a9f7c3"
        ],
        "devices": [
          "64b7f1e6f9c9d4e5b8a9f7c3"
        ],
        "distributionBoxes": [
          "64b7f1e6f9c9d4e5b8a9f7c3"
        ],
        "floorPlanKey": "floor-plans/uuid.png",
        "floorPlanUrl": "https://cdn.ecovolt.ai/floor-plans/uuid.png",
        "floorPlan": "floorPlan"
      },
      "room": "room",
      "system": "system",
      "createdAt": "2021-09-01",
      "updatedAt": "2021-09-01",
      "lastSeen": "2021-09-01",
      "isLocked": false,
      "isSpare": false,
      "deviceSchedule": {
        "oneTimeSchedules": [
          {
            "dateTime": "2023-10-31T06:00:00Z",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "monday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "tuesday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "wednesday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "thursday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "friday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "saturday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "sunday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "confirmationState": "PENDING"
      },
      "realTimePower": 1500,
      "realTimeCurrent": 6.5,
      "totalEnergyUsage": 0,
      "totalEnergySaved": 0,
      "autoUpdateAttempts": 0,
      "autoUpdateBlacklisted": false,
      "manualUpdateBlacklist": false,
      "lastAutoUpdateAttempt": "2024-08-25T15:00:00Z",
      "inactivityNotificationEnabled": false,
      "inactivityNotificationSentAt": "2024-08-25T15:00:00Z"
    }
  ],
  "isIRRemote": true,
  "irType": "AIRCON",
  "fanBrand": "KDK_T60AW",
  "fanSpeed": 1,
  "brand": "DAIKIN",
  "modelNumber": "FTKM50QV1M",
  "temperature": 24,
  "mode": "COOL",
  "fan": "AUTO",
  "swing": "OFF",
  "temperatureMin": 18,
  "temperatureMax": 30,
  "humidityMin": 30,
  "humidityMax": 80,
  "notificationThresholdHour": 4,
  "seriesType": "MAXWELL",
  "targetTemperature": 22,
  "smartMode": true,
  "lastSmartModeUpdate": "2024-01-01T12:00:00Z",
  "aggressiveness": 0.5,
  "deadbandTemperature": 0.5,
  "smartModeIntervalMinutes": 60
}

json

application/json

Get all air conditioners in a system (with filtering and sorting)

GET

http://localhost:8080

/api/aircon-control/system/{systemId}

Retrieve all air conditioners in a system with support for pagination, search, and sorting by multiple fields. Sortable fields: createdAt, updatedAt, deviceName, temperature, totalEnergyUsage, tenantName, userName, roomName, brand, lastSeen, chipModel, versionNumber, batchNumber, systemName, onStatus. Use comma-separated values for multiple sorts, e.g., "temperature,createdAt" with corresponding "desc,asc".

Get all air conditioners in a system (with filtering and sorting) › path Parameters

systemId

string · required

Get all air conditioners in a system (with filtering and sorting) › query Parameters

page

number · min: 1

Page number for pagination

Example: 1

Default: 1

size

number · min: 1 · max: 1000

Items per page

Example: 50

Default: 50

sort_by

string

Fields to sort by (comma-separated for multiple fields)

Example: createdAt,name

sort_order

string[]

Sort order for each field (comma-separated, must match sort_by length)

Enum values:

asc

desc

Example: desc,asc

search

string

Search keyword

Example: overheat

tenantId

string

Filter by Tenant ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Filter by Zone ID

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Filter by Room ID

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Filter by lock status

Example: false

onStatus

DeviceStatus · enum

Filter by device status

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

versionNumber

string

Filter by firmware version

Example: 1.0.0

isSpare

boolean

Filter by spare status. When true, returns only spare devices. When false, returns only non-spare devices. Omit to return all.

Example: false

Get all air conditioners in a system (with filtering and sorting) › Responses

List of air conditioners with pagination metadata

GetAirconControlsDto

FilteredAirconControlDto[] · required

List of aircon control devices with organizational hierarchy details

total

number · required

Total number of aircon control devices

Example: 10

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

GET/api/aircon-control/system/{systemId}

curl http://localhost:8080/api/aircon-control/system/:systemId

Example Responses

{
  "data": [
    {
      "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
      "macId": "1092384701928347",
      "deviceName": "Living Room AC",
      "onStatus": "ON",
      "targetState": "ON",
      "targetStateSetAt": "2026-05-25T08:00:00.000Z",
      "totalEnergyUsage": 500,
      "deviceNumber": 3,
      "batchNumber": 23,
      "chipModel": "ESP8266",
      "versionNumber": "1.0.0",
      "tenantId": "64b7f1e6f9c9d4e5b8a9f7c4",
      "tenantName": "Faculty of Engineering",
      "zoneId": "64b7f1e6f9c9d4e5b8a9f7c5",
      "zoneName": "Zone A",
      "roomId": "64b7f1e6f9c9d4e5b8a9f7c6",
      "roomName": "Room 101",
      "dbId": "64b7f1e6f9c9d4e5b8a9f7c7",
      "dbName": "Main Distribution Box",
      "systemId": "64b7f1e6f9c9d4e5b8a9f7c3",
      "systemName": "NUS Engineering Building",
      "realTimePower": 115,
      "realTimeCurrent": 0.5,
      "ssid": "XH001",
      "deviceSchedule": {
        "oneTimeSchedules": [
          {
            "dateTime": "2023-10-31T06:00:00Z",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "monday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "tuesday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "wednesday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "thursday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "friday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "saturday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "sunday": [
          {
            "time": "06:00",
            "action": "OFF",
            "actionValue": 24,
            "ruleName": "ruleName"
          }
        ],
        "confirmationState": "PENDING"
      },
      "lastSeen": "2024-10-15T12:30:00.000Z",
      "isLocked": false,
      "inactivityNotificationEnabled": false,
      "isIRRemote": true,
      "irType": "AIRCON",
      "fanBrand": "KDK_T60AW",
      "fanSpeed": 1,
      "brand": "DAIKIN",
      "modelNumber": "FTKM50QV1M",
      "temperature": 24,
      "mode": "COOL",
      "fan": "AUTO",
      "swing": "OFF",
      "seriesType": "MAXWELL",
      "smartDevices": [
        {
          "_id": "_id",
          "macId": "macId",
          "deviceName": "deviceName",
          "deviceType": "PLUG"
        }
      ],
      "smartMode": false,
      "targetTemperature": 22,
      "lastSmartModeUpdate": "2024-01-01T12:00:00Z",
      "aggressiveness": 0.5,
      "deadbandTemperature": 0.5,
      "smartModeIntervalMinutes": 60
    }
  ],
  "total": 10,
  "page": 1,
  "size": 10
}

json

application/json

MCB - Management Aircon Control - Control

Get Aircon Control by ID

GET

http://localhost:8080

/api/aircon-control/by-id/{deviceId}

Retrieves a single Aircon Control by its unique ID with full details including system, tenant, user, and room information.

Get Aircon Control by ID › path Parameters

deviceId

string · required

Get Aircon Control by ID › Responses

Aircon Control retrieved successfully

AirconControl

_id

string · required

Primary ID of the Device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceType

string · enum · required

Type of device (discriminator field)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the Device (from IoT device)

Example: 1092384701928347

deviceName

string · required

Name of the Device

Example: Living Room AC

deviceNumber

number · required

Unique device number for identification

Example: 1

onStatus

string · enum · required

Status of the Device (ON / OFF / INACTIVE / ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

location

string · required

Physical location or address where the device is installed

Example: Room 101, Building A

remarks

string · required

Remarks for the Device

batchNumber

number · required

Manufacturing batch number for tracking production groups

Example: 1

chipModel

string · enum · required

Hardware chip model identifier used in the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number currently running on the device

Example: 1.0.0

ssid

string · required

Network SSID (Wi-Fi name) that the device is connected to

Example: IoT-Network-5G

tenant

string · required

Tenant ID reference

object · required

Tagged Zone

room

string · required

Room ID reference

system

string · required

System ID reference

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

lastSeen

string · date-time · required

Last time the device was seen/reported

Example: 2021-09-01

isLocked

boolean · required

Whether the device is locked. When locked, the device on/off status cannot be toggled.

Example: false

totalEnergyUsage

number · required

Total cumulative energy usage in kWh

Example: 0

totalEnergySaved

number · required

Total energy saved through optimization in kWh

Example: 0

autoUpdateAttempts

number · required

Number of auto-update OTA attempts sent to this device

Example: 0

autoUpdateBlacklisted

boolean · required

Whether device is blacklisted from auto-updates (max retries exceeded)

Example: false

manualUpdateBlacklist

boolean · required

Whether device is manually blacklisted from auto-updates by admin

Example: false

inactivityNotificationEnabled

boolean · required

Whether inactivity notifications are enabled for this device

Default: false

isIRRemote

boolean · required

Whether this is an IR remote (true) or wired control (false)

Example: true

irType

string · enum · required

Type of IR device being controlled (AIRCON or FAN)

Enum values:

AIRCON

FAN

Example: AIRCON

Default: AIRCON

temperature

number · required

Temperature setting in degrees Celsius

Example: 24

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when targetState was last written. Used to expire stale SCHEDULED intents (24hr TTL). CLOUD intents do not expire.

Example: 2026-05-25T08:00:00.000Z

targetSource

string · enum

Origin of the pending targetState. Drives TTL behavior on reconcile. Only CLOUD / SCHEDULED are ever written here.

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: CLOUD

deviceModel

string

Model name or identifier of the device

Example: TP-Link HS110

deviceBrand

string

Brand or manufacturer of the device

Example: TP-Link

isSpare

boolean

Whether the device is a spare/inventory device. Spare devices can be filtered out of user-facing dashboards.

Example: false

object

Schedule configuration for the device. Contains recurring weekly schedules and one-time scheduled tasks.

realTimePower

number

Real-time power consumption in watts

Example: 1500

realTimeCurrent

number

Real-time current in amperes

Example: 6.5

lastAutoUpdateAttempt

string · date-time

Timestamp of last auto-update OTA attempt

inactivityNotificationSentAt

string · date-time

Timestamp when the last inactivity notification was sent for this device

Device[]

List of smart devices controlled by this aircon sensor

fanBrand

string · enum

Brand of the fan unit (only applicable when irType is FAN)

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Example: KDK_T60AW

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

brand

string · enum

Brand of the AC unit being controlled

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number (e.g. FTKM50QV1M). Required for consumption estimation via AirconModelSpec lookup. Stored uppercased and trimmed.

Example: FTKM50QV1M

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

temperatureMin

number

Min ambient temperature threshold in Celsius for alerts

Example: 18

temperatureMax

number

Max ambient temperature threshold in Celsius for alerts

Example: 30

humidityMin

number

Min ambient humidity threshold percentage for alerts

Example: 30

humidityMax

number

Max ambient humidity threshold percentage for alerts

Example: 80

notificationThresholdHour

number

Minimum hours between repeated notifications for the same alert type

Example: 4

Default: 4

seriesType

string · enum

Series type — NORMAL (control only) or PRO (control + ambient temp/humidity sensing)

Enum values:

MAXWELL

MAXWELL_PRO

Example: MAXWELL

Default: MAXWELL

targetTemperature

number

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: true

lastSmartModeUpdate

string · date-time

Timestamp of the last update to smart mode settings (used for tracking when thresholds were last updated)

Example: 2024-01-01T12:00:00Z

aggressiveness

number · min: 0 · max: 1

Example: 0.5

Default: 0.5

deadbandTemperature

number · min: 0 · max: 3

Smart mode deadband in °C. If the ambient temperature is within this range of the target, no setpoint adjustment is sent. Prevents oscillation and unnecessary compressor cycling. Default: 0.5.

Example: 0.5

Default: 0.5

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum interval in minutes between smart mode recalculations. Prevents excessive updates. Typical values: 15, 30, 60. Default: 60.

Example: 60

Default: 60

Get all air conditioners in a system (with filtering and sorting)

GET

http://localhost:8080

/api/aircon-control/system/{systemId}

Get all air conditioners in a system (with filtering and sorting) › path Parameters

systemId

string · required

Get all air conditioners in a system (with filtering and sorting) › query Parameters

page

number · min: 1

Page number for pagination

Example: 1

Default: 1

size

number · min: 1 · max: 1000

Items per page

Example: 50

Default: 50

sort_by

string

Fields to sort by (comma-separated for multiple fields)

Example: createdAt,name

sort_order

string[]

Sort order for each field (comma-separated, must match sort_by length)

Enum values:

asc

desc

Example: desc,asc

search

string

Search keyword

Example: overheat

tenantId

string

Filter by Tenant ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Filter by Zone ID

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Filter by Room ID

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Filter by lock status

Example: false

onStatus

DeviceStatus · enum

Filter by device status

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

versionNumber

string

Filter by firmware version

Example: 1.0.0

isSpare

boolean

Filter by spare status. When true, returns only spare devices. When false, returns only non-spare devices. Omit to return all.

Example: false

Get all air conditioners in a system (with filtering and sorting) › Responses

List of air conditioners with pagination metadata

GetAirconControlsDto

FilteredAirconControlDto[] · required

List of aircon control devices with organizational hierarchy details

total

number · required

Total number of aircon control devices

Example: 10

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10