Overview of Circuit Breaker Open Capabilities

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.

• Subscribe to the message service.
• Integrate with the message queue.

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 IoT 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 IoT 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 IoT 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 IoT 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"
}