Overview of Circuit Breaker Open Capabilities

Last Updated on : 2024-06-13 10:48:59download

This topic describes how to integrate with open capabilities of circuit breakers.

API description

Alarm threshold management

API name API endpoint
Set Over-Voltage Protection Value POST:/v1.0/electric-energy/{device_id}/actions/voltage-over
Set Power Limit POST:/v1.0/electric-energy/{device_id}/actions/power-limit
Set Current Limit POST:/v1.0/electric-energy/{device_id}/actions/current-limit
Set Leakage Alarm Value POST:/v1.0/electric-energy/{device_id}/actions/leak-warn-value
Set Leakage Action Value POST:/v1.0/electric-energy/{device_id}/actions/leak-action-value
Set Electricity Consumption Alarm Value POST:/v1.0/electric-energy/{device_id}/actions/electric-warn
Set Under-Voltage Protection Value POST:/v1.0/electric-energy/{device_id}/actions/voltage-under
Set Over-Temperature Protection Value POST:/v1.0/electric-energy/{device_id}/actions/temp-over

Switch management

API name API endpoint
Set Enabling Switch POST:/v1.0/electric-energy/{device_id}/actions/hand-enable
Set Circuit Switch POST:/v1.0/electric-energy/{device_id}/actions/switch

Data management

API name API endpoint
Get Real-Time Data GET:/v1.0/electric-energy/{device_id}/actions/realtime-data

Circuit breaker event format

After you subscribe to the message service for a cloud development project, you will receive event messages from the associated circuit breakers.

Report monitoring data

API description

The circuit breaker reports device monitoring data.

Description of status

The response data is classified by the code of data types.

List of data types

DP code for monitoring Data description Data type
switch Device switch Integer type. Valid values:
  • 0: off
  • 1: on
power_current Actual power Long type, in W.
voltage_current Actual voltage Long type, in V.
current_max Maximum current Long type, in mA.
cur_current Actual current Long type, in mA.
device_info Device information String type, up to 128 bytes in length.
status_query Status synchronization String type, up to 128 bytes in length.
temp_current Actual temperature Long type, in °C.
voltage_under Under-voltage value Long type, in V.
voltage_over Over-voltage value Long type, in V.
leakage_warn_value Leakage alarm value Long type, in mA.
leakage_fault_value Leakage fault value Long type, in mA.
leakage_current Leakage current Long type, in A.
leakage_protection Leakage protection Enum type. Valid values:
  • no_leak_pro_without_value: no leakage protection, without leakage value displayed.
  • no_leak_pro_with_value: no leakage protection, with leakage value displayed.
  • leak_pro_with_value: leakage protection enabled, with leakage value displayed.
switch_enabled Enabling switch Integer type. Valid values:
  • 0: off
  • 1: on
over_current_duration Overcurrent duration Long type, in seconds.
fault Fault alarm Enum type. Valid values:
  • short_circuit_alarm: short circuit alarm
  • surge_alarm: surge alarm
  • overload_alarm: overload alarm
  • ov_vol: over-voltage alarm
  • undervoltage_alarm: under-voltage alarm
  • temp_dif_fault: temperature anomaly alarm
  • leakagecurr_alarm: leakage alarm
  • self_test_alarm: leakage self-check anomaly
  • fire_alarm: electric arc alarm
  • high_power_alarm: high power alarm
  • ov_cr: overcurrent fault
  • outage_alarm: outage event alarm
  • magnetism_alarm: magnetic interference alarm
  • credit_alarm: insufficient balance alarm
alarm_level Alarm severity level Enum type. Valid values:
  • general: general
  • serious: serious
  • urgent: urgent
device_alarm Device alarm String type, up to 128 bytes in length.
alarm_event_content Alarm content String type, up to 128 bytes in length.
fire_alarm_type Fire alarm type Enum type. Valid values:
  • fire_alarm: fire alarm
  • device_fault: device fault
  • device_alarm: device alarm
alarm_trace_time Event occurrence time String type, up to 128 bytes in length.
alarm_result_content Event processing result String type, up to 128 bytes in length.
alarm_value Event value Long type.
alarm_unit Alarm unit String type, up to 128 bytes in length.
alarm_process_time Alarm processing time String type, up to 128 bytes in length.
phase_a Report phase-A voltage, current, and power String type, up to 128 bytes in length.
phase_b Report phase-B voltage, current, and power String type, up to 128 bytes in length.
phase_c Report phase-C voltage, current, and power String type, up to 128 bytes in length.
leakage_action_value Leakage action value Long type, in mA.
over_temp_value Over-temperature value Long type, in °C.
over_vol_protect_time Over-voltage and under-voltage protection time Long type, in minutes.
over_vol_recovery_time Over-voltage and under-voltage protection recovery time Long type, in minutes.
power_effective Active power Long type, in W.
power_reactive Reactive power Long type, in W.
power_factor Power factor Long type.
supply_frequency Grid power supply frequency Long type.
switch_times On/off times Long type.
short_times Number of times a short circuit occurred Long type.
electric_total Total electricity consumption Long type, in kW·h.
electric_daily Daily electricity consumption Long type, in kW·h.
electric_month Monthly electricity consumption Long type, in kW·h.
residual_electricity Remaining electricity allowance Long type, in kW.
power_limit Power limit Long type, in W.
electric_warm_value Electricity consumption alarm value Long type, in kW.
forward_energy_total Forward total active electricity Long type, in kW.
energy_reactive Reactive electricity Long type, in kW.
power_apparent Apparent power Long type, in kV.
cold_stall_userdata Usage of shared cold water Long type.
cold_stall_type Sharing type of cold water Enum type. Valid values:
  • square_area: by area in square units
  • ignore: ignore
  • consumption: by electricity consumption
  • proportion: by proportion
  • lease: lease
  • power: by power
hot_stall_userdata Usage of shared hot water Long type.
hot_stall_type Sharing type of hot water Enum type. Valid values:
  • square_area: by area in square units
  • ignore: ignore
  • consumption: by electricity consumption
  • proportion: by proportion
  • lease: lease
  • power: by power
switch_state Switch status Integer type. Valid values:
  • 0: off
  • 1: on
d_end_time Last reading time of a day String type, up to 255 bytes in length.
m_end_time Last reading time of a month String type, up to 255 bytes in length.

Example

{
    "dataId": "AAXRV4BrtW9BRB9A2JY((((",
    "devId": "6ca****",
    "productKey": "e6rz6vba81wm****",
    "status": [
        {
            "44": 104061476,
            "code": "electric_total",
            "t": 1637548630455,
            "value": 104061476
        }
    ]
}

Circuit breaker event format v1.0

Device event messages are compatible with v1.0 format. If you want to subscribe to the v1.0 format, please contact Tuya’s staff. For more information about the integration process, see Device event format v1.0.

Report cumulative electricity consumption

API description

The cumulative electricity consumption of a circuit breaker is reported to Tuya Cloud. You will also be notified.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. Default value: edge_device. Yes
eventType String The type of a specified event. Default value: edge_report_data. Yes
data String The data string in the JSON format. Yes
Description of data
Parameter name Data type Description Required
mode String The mode of a specified event. Default value: energy_power_data. Yes
data String The event string in the JSON format. Yes
Description of event string
Parameter name Data type Description Required
deviceId String The ID of a specified Tuya device. Yes
eventId String The ID of a reported event. Yes
sumEnergy Double The cumulative energy consumption. Yes
happenTime Long The 13-digit timestamp. Yes

Example

{
    "data": "{\"mode\":\"energy_power_data\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"eventId\\\":"123456789" ,\\\"sumEnergy\\\":1}}",
    "bizCode": "edge_device",
    "eventType": "edge_report_data"
}

Report alarms

API description

The alarms of a circuit breaker are reported to Tuya Cloud. You will also be notified.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. Default value: edge_device. Yes
eventType String The type of a specified event. Default value: edge_report_data. Yes
data String The data string in the JSON format. Yes
Description of data
Parameter name Data type Description Required
mode String The mode of a specified event. Default value: energy_alarm. Yes
data String The event string in the JSON format. Yes
Description of event string
Parameter name Data type Description Required
deviceId String The ID of a specified Tuya device. Yes
messageId String The ID of a specified message. Yes
type Integer The type. Valid values:
  • 0: alarm
  • 1: fault
Yes
code String The code of a specified alarm or fault. Yes
content String The content of a specified alarm or fault. Yes
confirmEnable Boolean Specifies whether an alarm is processed. true: already processed. Yes
happenTime Long The 13-digit timestamp. Yes

Example

{
    "data": "{\"mode\":\"energy_alarm\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"type\\\":1,\\\"code\\\":\\\"alarm",\\\"content\\\":\\\"Electricity consumption alarm",\\\"confirmEnable\\\":false}}",
    "bizCode": "edge_device",
    "eventType": "edge_report_data"
}

Report on/off status

API description

The on/off status of a circuit breaker is reported to Tuya Cloud. You will also be notified.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. Default value: edge_device. Yes
eventType String The type of a specified event. Default value: edge_report_data. Yes
data String The data string in the JSON format. Yes
Description of data
Parameter name Data type Description Required
mode String The mode of a specified event. Default value: energy_switch_status. Yes
data String The event string in the JSON format. Yes
Description of event string
Parameter name Data type Description Required
deviceId String The ID of a specified Tuya device. Yes
switchStatus Boolean
  • true: The circuit breaker contacts are closed.
  • false: The circuit breaker contacts are opened.
Yes
happenTime Long The 13-digit timestamp. Yes

Example

{
    "data": "{\"mode\":\"energy_switch_status\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"switchStatus\\\":true}}",
    "bizCode": "edge_device",
    "eventType": "edge_report_data"
}

Report the collected data

API description

The data collected by a circuit breaker is reported to Tuya Cloud. You will also be notified.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. Default value: edge_device. Yes
eventType String The type of a specified event. Default value: edge_report_data. Yes
data String The data string in the JSON format. Yes
Description of data
Parameter name Data type Description Required
mode String The mode of a specified event. Default value: energy_monitor_data. Yes
data String The event string in the JSON format. Yes
Description of event string
Parameter name Data type Description Required
deviceId String The ID of a specified Tuya device. Yes
type String The sampling metric. For more information, see the list of type sampling metrics. Yes
value Double The value of a sampling metric. Yes
happenTime Long The 13-digit timestamp. Yes
List of type sampling metrics
type Description
voltagePhaseA Phase-A voltage, in V.
currentPhaseA Phase-A current, in A.
powerPhaseA Phase-A power, in kW.
electricityPhaseA Phase-A electricity consumption, in kW·h.
voltagePhaseB Phase-B voltage, in V.
currentPhaseB Phase-B current, in A.
powerPhaseB Phase-B power, in kW.
electricityPhaseB Phase-B electricity consumption, in kW·h.
voltagePhaseC Phase-C voltage, in V.
currentPhaseC Phase-C current, in A.
powerPhaseC Phase-C power, in kW.
electricityPhaseC Phase-C electricity consumption, in kW·h.
activePower Active electricity, in kW·h.
reactivePower Reactive electricity, in kW·h.
currentA Actual current, in A.
maxCurrent Maximum current, in A.
duration Duration of maximum current, in s.
voltageA Actual voltage, in V.
powerA Actual power, in kW.
tempA Actual temperature, in °C.
under Under-voltage value, in V.
over Over-voltage value, in V.
currentLeakValue Actual leakage value, in mA.
leakWarnValue Leakage alarm value, in mA.
leakActionValue Leakage action value, in mA.
isLeakage Specifies whether leakage occurs. Valid values:
  • 0: no leakage current value displayed, no leakage protection function.
  • 1: leakage current value displayed, with leakage protection function.
  • 2: leakage current value displayed, no leakage protection function. You can change the leakage alarm value.
handEnabled Specifies whether to lock the manual switch value. Valid value:
  • 0: unlock
  • 1: lock
powerP Active power, in W.
powerQ Reactive power, in var.
pf Frequency, in Hz.
switchTime On/off times
shortTime Number of times a short circuit occurred
powerMax Power limit, in W.
eResidual Remaining electricity, in kW·h.
eWarn Alarm value of electricity consumption, in kW·h.
tempMax Value of over-temperature protection, in °C.
vpOtime Duration of over-voltage and under-voltage protection action, in s.
vpRtime Over-voltage and under-voltage protection recovery time, in s.
electric_daily Daily electricity consumption, in kW·h.
d_end_time The 13-digit timestamp when the daily electricity consumption is read.
electric_month Monthly electricity consumption, in kW·h.
m_end_time The 13-digit timestamp when the monthly electricity consumption is read.

Example

{
    "data": "{\"mode\":\"energy_monitor_data\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"type\\\":\\\"voltagePhaseA\\\",\\\"value\\\":217.6}}",
    "bizCode": "edge_device",
    "eventType": "edge_report_data"
}