Distribution Box - Management

Get Distribution Box by ID

GET

http://localhost:8080

/api/distribution-box/by-id/{id}

Retrieves a single Distribution Box by its unique ID with full details including system, tenant, room, and associated MCBs.

Get Distribution Box by ID › path Parameters

id

string · required

Get Distribution Box by ID › Responses

Distribution Box retrieved successfully

DistributionBox

_id

string · required

Primary ID of the Distribution Box

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name/identifier of the Distribution Box

Example: Main DB Box - Floor 1

system

string · required

System to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date and time when the distribution box was created

updatedAt

string · date-time · required

Date and time when the distribution box was last updated

boxNumber

number

Unique box number for identification within a system

Example: 1

numberOfRows

number

Number of rows in the distribution box

Example: 1

mcbs

string[]

Array of MCB IDs or partially populated MCB objects (_id, deviceName, macId, onStatus)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

hasMainBreaker

boolean

Whether the distribution box has a main circuit breaker

Example: true

mainBreakerRating

number

Main breaker rating in amperes (if hasMainBreaker is true)

Example: 63

location

string

Physical location where the distribution box is installed

Example: Ground Floor, Electrical Room

remarks

string

Additional remarks or notes about the distribution box

Example: Main distribution panel installed in 2024

tenant

string

Tenant to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c4

zone

string

Zone to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c5

room

string

Room where this distribution box is located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

SandboxDevice[]

Array of sandbox (non-smart) devices in the distribution box

SandboxWire[]

Array of wire connections between devices in the distribution box

digitalTwinWidth

number

Width of the digital twin canvas in pixels

Example: 1200

digitalTwinHeight

number

Height of the digital twin canvas in pixels

Example: 800

singleLineDiagramKey

string

S3 key for the single line diagram image

Example: single-line-diagrams/abc123-def456.png

singleLineDiagramUrl

string

CDN URL for the single line diagram image

Example: https://cdn.example.com/single-line-diagrams/abc123-def456.png

GET/api/distribution-box/by-id/{id}

curl http://localhost:8080/api/distribution-box/by-id/:id

Example Responses

{
  "_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"
}

json

application/json

Get all Distribution Boxes with pagination and sorting

GET

http://localhost:8080

/api/distribution-box/system/{systemId}

Retrieves a paginated list of Distribution Boxes for a system. Supports filtering by tenant, zone, and room. Includes search and comprehensive sorting capabilities (by createdAt, updatedAt, name, boxNumber, location, numberOfRows, totalMCBs, totalEnergyUsage, tenantName, zoneName, systemName).

Get all Distribution Boxes with pagination and sorting › path Parameters

systemId

string · required

Get all Distribution Boxes with pagination 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

search

string

Search keyword in error message or metadata

Example: overheat

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

tenantId

string

Filter by tenant ID

Example: 507f1f77bcf86cd799439011

zoneId

string

Filter by zone ID

Example: 507f1f77bcf86cd799439012

roomId

string

Filter by room ID

Example: 507f1f77bcf86cd799439013

Get all Distribution Boxes with pagination and sorting › Responses

200

List of Distribution Boxes retrieved successfully

GetDistributionBoxesDto

DistributionBox[] · required

Array of Distribution Boxes

total

number · required

Total number of Distribution Boxes

Example: 100

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

GET/api/distribution-box/system/{systemId}

curl http://localhost:8080/api/distribution-box/system/:systemId

Example Responses

{
  "data": [
    {
      "_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"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 10
}

json

application/json

Get all MCBs in Distribution Box

GET

http://localhost:8080

/api/distribution-box/{id}/mcbs

Retrieves all MCBs contained in a Distribution Box with their full details including current status and energy usage.

Get all MCBs in Distribution Box › path Parameters

id

string · required

Get all MCBs in Distribution Box › Responses

MCBs retrieved successfully

MCB[]

MCB

_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

mcbType

string · enum · required

Type of MCB

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

Example: COIL

mcbPoles

string · enum · required

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

ratedCurrent

number · required

Rated current capacity in amperes

Example: 16

ratedVoltage

number · required

Rated voltage in volts

Example: 230

realTimeVoltage

number · required

Real-time voltage in volts

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.95

object · required

Parent distribution box containing this MCB

isReversePower

boolean · required

Whether power/current readings should be reversed (made absolute). When true, negative values are converted to positive.

Example: false

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

measurementType

string · enum

Type of load/circuit being measured by this MCB

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: SSO

digitalTwinX

number

X coordinate for digital twin SVG positioning

Example: 150.5

rowLine

number

Row line number (1-6) the MCB is connected to

Example: 1

slotNumber

number

Slot/position number on the busbar

Example: 3

voltageMax

number

Max Threshold voltage reading in volts

Example: 240

currentMax

number

Max Threshold current reading in amps

Example: 10

powerMax

number

Max Threshold power reading in watts

Example: 100

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications of the same type

Example: 4

GET/api/distribution-box/{id}/mcbs

curl http://localhost:8080/api/distribution-box/:id/mcbs

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": [
        {
          "_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"
        }
      ],
      "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",
    "mcbType": "COIL",
    "mcbPoles": "SINGLE_POLE",
    "measurementType": "SSO",
    "ratedCurrent": 16,
    "ratedVoltage": 230,
    "realTimeVoltage": 230,
    "powerFactor": 0.95,
    "distributionBox": {
      "_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"
    },
    "digitalTwinX": 150.5,
    "rowLine": 1,
    "slotNumber": 3,
    "isReversePower": false,
    "voltageMax": 240,
    "currentMax": 10,
    "powerMax": 100,
    "notificationThresholdHour": 4
  }
]

json

application/json

Get Distribution Box energy usage

GET

http://localhost:8080

/api/distribution-box/{id}/energy-usage

Retrieves current energy usage data for a specific distribution box. Returns the sum of all MCBs contained in this distribution box including voltage, current, power, and energy consumption.

Get Distribution Box energy usage › path Parameters

id

string · required

Get Distribution Box energy usage › Responses

Energy usage retrieved successfully

GetDistributionBoxEnergyUsageDto

distributionBoxId

string · required

Distribution Box ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Distribution Box name

Example: Main DB Box - Floor 1

totalEnergyUsage

number · required

Total energy usage in kWh (sum of all MCBs)

Example: 1250.75

mcbCount

number · required

Number of MCBs in this distribution box

Example: 12

GetMCBEnergyUsageDto[] · required

Individual MCB energy usage details

Get system distribution box energy usage

GET

http://localhost:8080

/api/distribution-box/system/{systemId}/energy-usage

Retrieves aggregated energy usage for all distribution boxes in a system. Provides system-wide distribution box analytics including total energy consumption and individual box breakdowns. Requires CIRCUIT_BREAKER feature.

Get system distribution box energy usage › path Parameters

systemId

string · required

Get system distribution box energy usage › Responses

200

Aggregated energy usage retrieved successfully

GetAggregatedDistributionBoxEnergyUsageDto

totalEnergyUsage

number · required

Total aggregated energy usage in kWh

Example: 5250.75

distributionBoxCount

number · required

Number of distribution boxes included

Example: 5

GetDistributionBoxEnergyUsageDto[] · required

Individual distribution box energy usage details

Get tenant distribution box energy usage

GET

http://localhost:8080

/api/distribution-box/tenant/{tenantId}/energy-usage

Retrieves aggregated energy usage for all distribution boxes assigned to a specific tenant. Useful for tenant billing and energy monitoring.

Get tenant distribution box energy usage › path Parameters

tenantId

string · required

Get tenant distribution box energy usage › Responses

200

Aggregated energy usage retrieved successfully

GetAggregatedDistributionBoxEnergyUsageDto

totalEnergyUsage

number · required

Total aggregated energy usage in kWh

Example: 5250.75

distributionBoxCount

number · required

Number of distribution boxes included

Example: 5

GetDistributionBoxEnergyUsageDto[] · required

Individual distribution box energy usage details

DistributionBox Device - Maintenance

Get Distribution Box by ID

GET

http://localhost:8080

/api/distribution-box/by-id/{id}

Retrieves a single Distribution Box by its unique ID with full details including system, tenant, room, and associated MCBs.

Get Distribution Box by ID › path Parameters

id

string · required

Get Distribution Box by ID › Responses

Distribution Box retrieved successfully

DistributionBox

_id

string · required

Primary ID of the Distribution Box

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name/identifier of the Distribution Box

Example: Main DB Box - Floor 1

system

string · required

System to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date and time when the distribution box was created

updatedAt

string · date-time · required

Date and time when the distribution box was last updated

boxNumber

number

Unique box number for identification within a system

Example: 1

numberOfRows

number

Number of rows in the distribution box

Example: 1

mcbs

string[]

Array of MCB IDs or partially populated MCB objects (_id, deviceName, macId, onStatus)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

hasMainBreaker

boolean

Whether the distribution box has a main circuit breaker

Example: true

mainBreakerRating

number

Main breaker rating in amperes (if hasMainBreaker is true)

Example: 63

location

string

Physical location where the distribution box is installed

Example: Ground Floor, Electrical Room

remarks

string

Additional remarks or notes about the distribution box

Example: Main distribution panel installed in 2024

tenant

string

Tenant to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c4

zone

string

Zone to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c5

room

string

Room where this distribution box is located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

SandboxDevice[]

Array of sandbox (non-smart) devices in the distribution box

SandboxWire[]

Array of wire connections between devices in the distribution box

digitalTwinWidth

number

Width of the digital twin canvas in pixels

Example: 1200

digitalTwinHeight

number

Height of the digital twin canvas in pixels

Example: 800

singleLineDiagramKey

string

S3 key for the single line diagram image

Example: single-line-diagrams/abc123-def456.png

singleLineDiagramUrl

string

CDN URL for the single line diagram image

Example: https://cdn.example.com/single-line-diagrams/abc123-def456.png

Get all Distribution Boxes with pagination and sorting

GET

http://localhost:8080

/api/distribution-box/system/{systemId}

Get all Distribution Boxes with pagination and sorting › path Parameters

systemId

string · required

Get all Distribution Boxes with pagination 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

search

string

Search keyword in error message or metadata

Example: overheat

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

tenantId

string

Filter by tenant ID

Example: 507f1f77bcf86cd799439011

zoneId

string

Filter by zone ID

Example: 507f1f77bcf86cd799439012

roomId

string

Filter by room ID

Example: 507f1f77bcf86cd799439013

Get all Distribution Boxes with pagination and sorting › Responses

200

List of Distribution Boxes retrieved successfully

GetDistributionBoxesDto

DistributionBox[] · required

Array of Distribution Boxes

total

number · required

Total number of Distribution Boxes

Example: 100

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

Get all MCBs in Distribution Box

GET

http://localhost:8080

/api/distribution-box/{id}/mcbs

Retrieves all MCBs contained in a Distribution Box with their full details including current status and energy usage.

Get all MCBs in Distribution Box › path Parameters

id

string · required

Get all MCBs in Distribution Box › Responses

MCBs retrieved successfully

MCB[]

MCB

_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

mcbType

string · enum · required

Type of MCB

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

Example: COIL

mcbPoles

string · enum · required

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

ratedCurrent

number · required

Rated current capacity in amperes

Example: 16

ratedVoltage

number · required

Rated voltage in volts

Example: 230

realTimeVoltage

number · required

Real-time voltage in volts

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.95

object · required

Parent distribution box containing this MCB

isReversePower

boolean · required

Whether power/current readings should be reversed (made absolute). When true, negative values are converted to positive.

Example: false

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

measurementType

string · enum

Type of load/circuit being measured by this MCB

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: SSO

digitalTwinX

number

X coordinate for digital twin SVG positioning

Example: 150.5

rowLine

number

Row line number (1-6) the MCB is connected to

Example: 1

slotNumber

number

Slot/position number on the busbar

Example: 3

voltageMax

number

Max Threshold voltage reading in volts

Example: 240

currentMax

number

Max Threshold current reading in amps

Example: 10

powerMax

number

Max Threshold power reading in watts

Example: 100

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications of the same type

Example: 4

Get Distribution Box energy usage

GET

http://localhost:8080

/api/distribution-box/{id}/energy-usage

Retrieves current energy usage data for a specific distribution box. Returns the sum of all MCBs contained in this distribution box including voltage, current, power, and energy consumption.

Get Distribution Box energy usage › path Parameters

id

string · required

Get Distribution Box energy usage › Responses

Energy usage retrieved successfully

GetDistributionBoxEnergyUsageDto

distributionBoxId

string · required

Distribution Box ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Distribution Box name

Example: Main DB Box - Floor 1

totalEnergyUsage

number · required

Total energy usage in kWh (sum of all MCBs)

Example: 1250.75

mcbCount

number · required

Number of MCBs in this distribution box

Example: 12

GetMCBEnergyUsageDto[] · required

Individual MCB energy usage details

Get system distribution box energy usage

GET

http://localhost:8080

/api/distribution-box/system/{systemId}/energy-usage

Get system distribution box energy usage › path Parameters

systemId

string · required

Get system distribution box energy usage › Responses

200

Aggregated energy usage retrieved successfully

GetAggregatedDistributionBoxEnergyUsageDto

totalEnergyUsage

number · required

Total aggregated energy usage in kWh

Example: 5250.75

distributionBoxCount

number · required

Number of distribution boxes included

Example: 5

GetDistributionBoxEnergyUsageDto[] · required

Individual distribution box energy usage details

Get tenant distribution box energy usage

GET

http://localhost:8080

/api/distribution-box/tenant/{tenantId}/energy-usage

Retrieves aggregated energy usage for all distribution boxes assigned to a specific tenant. Useful for tenant billing and energy monitoring.

Get tenant distribution box energy usage › path Parameters

tenantId

string · required

Get tenant distribution box energy usage › Responses

200

Aggregated energy usage retrieved successfully

GetAggregatedDistributionBoxEnergyUsageDto

totalEnergyUsage

number · required

Total aggregated energy usage in kWh

Example: 5250.75

distributionBoxCount

number · required

Number of distribution boxes included

Example: 5

GetDistributionBoxEnergyUsageDto[] · required

Individual distribution box energy usage details