Device

Toggle device ON/OFF

POST

http://localhost:8080

/api/device/system/{systemId}/toggle

Remotely toggle a device on or off. For SmartSwitch devices, all gangs will be turned ON or OFF.

Toggle device ON/OFF › path Parameters

systemId

string · required

Toggle device ON/OFF › Request Body

ToggleDeviceStatusDto

deviceId

string · required

Unique identifier of the device to be toggled

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum

Desired power state. Use ON to turn the device on (all gangs for SmartSwitch), or OFF to turn it off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

Toggle device ON/OFF › Responses

Device toggled successfully

Device

_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

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

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

POST/api/device/system/{systemId}/toggle

curl http://localhost:8080/api/device/system/:systemId/toggle \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "deviceId": "64b7f1e6f9c9d4e5b8a9f7c3",
  "onStatus": "ON"
}'

Example Request Body

{
  "deviceId": "64b7f1e6f9c9d4e5b8a9f7c3",
  "onStatus": "ON"
}

json

Example Responses

{
  "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
  "deviceType": "PLUG",
  "macId": "1092384701928347",
  "deviceName": "Living Room AC",
  "deviceNumber": 1,
  "onStatus": "ON",
  "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": [
      "string"
    ],
    "devices": [
      null
    ],
    "distributionBoxes": [
      {
        "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
        "name": "Main DB Box - Floor 1",
        "boxNumber": 1,
        "numberOfRows": 1,
        "mcbs": [
          "64b7f1e6f9c9d4e5b8a9f7c3"
        ],
        "hasMainBreaker": true,
        "mainBreakerRating": 63,
        "location": "Ground Floor, Electrical Room",
        "remarks": "Main distribution panel installed in 2024",
        "system": "64b7f1e6f9c9d4e5b8a9f7c3",
        "tenant": "64b7f1e6f9c9d4e5b8a9f7c4",
        "zone": "64b7f1e6f9c9d4e5b8a9f7c5",
        "room": "64b7f1e6f9c9d4e5b8a9f7c6",
        "sandboxDevices": [
          {
            "id": "sandbox-device-1",
            "type": "DUMB_MCB",
            "name": "Kitchen Lights",
            "digitalTwinX": 400,
            "rowLine": 2,
            "ratedCurrent": 16,
            "ratedVoltage": 230,
            "mcbType": "BUILT_IN",
            "mcbPoles": "SINGLE_POLE",
            "leakageCurrent": 30,
            "color": "#94a3b8",
            "notes": "Connected to kitchen circuit"
          }
        ],
        "sandboxWires": [
          {
            "id": "wire-1",
            "from": {
              "deviceId": "sandbox-device-1",
              "deviceType": "DUMB_MCB",
              "side": "LEFT"
            },
            "to": {
              "deviceId": "sandbox-device-1",
              "deviceType": "DUMB_MCB",
              "side": "LEFT"
            },
            "color": "#fbbf24",
            "thickness": 3,
            "label": "Phase 1"
          }
        ],
        "digitalTwinWidth": 1200,
        "digitalTwinHeight": 800,
        "singleLineDiagramKey": "single-line-diagrams/abc123-def456.png",
        "singleLineDiagramUrl": "https://cdn.example.com/single-line-diagrams/abc123-def456.png",
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z"
      }
    ],
    "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"
}

json

application/json

Bulk toggle multiple devices ON/OFF

POST

http://localhost:8080

/api/device/system/{systemId}/toggle/bulk

Remotely toggle multiple devices (plugs, MCBs, smart switches, aircon controls, water meters) on or off simultaneously. All devices receive the same power state. For SmartSwitch devices, all gangs will be turned ON or OFF. Devices that are locked or encounter errors during toggling will be silently skipped. Requires SUPERADMIN or ADMIN role.

Bulk toggle multiple devices ON/OFF › path Parameters

systemId

string · required

Bulk toggle multiple devices ON/OFF › Request Body

BulkToggleDeviceDto

deviceIds

string[] · required

Array of device IDs to toggle

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

onStatus

string · enum

Desired power state for all devices. Use ON to turn all devices on (all gangs for SmartSwitch), or OFF to turn all devices off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

Bulk toggle multiple devices ON/OFF › Responses

Bulk toggle operation completed successfully

No data returned

Tenant - Management Device - Management

Toggle device ON/OFF

POST

http://localhost:8080

/api/device/system/{systemId}/toggle

Remotely toggle a device on or off. For SmartSwitch devices, all gangs will be turned ON or OFF.

Toggle device ON/OFF › path Parameters

systemId

string · required

Toggle device ON/OFF › Request Body

ToggleDeviceStatusDto

deviceId

string · required

Unique identifier of the device to be toggled

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum

Desired power state. Use ON to turn the device on (all gangs for SmartSwitch), or OFF to turn it off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

Toggle device ON/OFF › Responses

Device toggled successfully

Device

_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

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

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

Bulk toggle multiple devices ON/OFF

POST

http://localhost:8080

/api/device/system/{systemId}/toggle/bulk

Bulk toggle multiple devices ON/OFF › path Parameters

systemId

string · required

Bulk toggle multiple devices ON/OFF › Request Body

BulkToggleDeviceDto

deviceIds

string[] · required

Array of device IDs to toggle

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

onStatus

string · enum

Desired power state for all devices. Use ON to turn all devices on (all gangs for SmartSwitch), or OFF to turn all devices off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

Bulk toggle multiple devices ON/OFF › Responses

Bulk toggle operation completed successfully

No data returned