1. Start to Use

1.1 Preparation

Step 1: Please make sure the network connected to the NSPanel Pro is operating normally.Step 2: Under the same LAN, the mDNS broadcast of the device can be searched in the LAN.

Notice:

If you have several gateways, you can get the corresponding IP address to access the specified gateway through log in to your wireless router and check the IP address of the gateway in DHCP.

1.2 Get started

Call the [Access Token] interface, and get an error response, prompting to click <Done>. Note that after pressing, the interface access is valid for no more than 5 minutes.

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/bridge/access_token' --header 'Content-Type: application/json'
// Response
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

Click <Done> and call the [Access Token] interface again. The response is successful, and the token is obtained.

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/bridge/access_token' --header 'Content-Type: application/json'
// Response
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Verify token. Call the [Get Device List] interface. The response is successful, and the device list is obtained.

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'
// Response
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocol": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

2. Core Concept

2.1 Development Interface Address

The gateway Web API interface has two access methods (based on IP or domain name), usually the root path is /open-api/v1/rest/< specific function module >

// IP access
http://<IP address>:8081/open-api/v1/rest/bridge

// Domain name access
http://<domain address>:8081/open-api/v1/rest/bridge

2.2 Device Display Category & Capabilities

Device display category (DisplayCategory). Device display category is used to identify (device) specific categories, such as switch, plug, light, etc. This information will determine the UI display effect of the device in the gateway.
Device Capability. Device capability is used to describe the specific sub-functions of the device. Such as power control, brightness control, color temperature control, etc. A single device can support 1 or more capabilities.
- Ability name. Identify a specific capability. For example power, brightness.
- Ability permission. Identify whether the capability supports reading or writing.
  - Read-only (read). Obtain the status value or configuration information related to this capability. For example, the states of power are on (open) and off (closed).
  - Write-only (write). Update the status value or configuration information related to the capability. For example, the power status can be changed to off through the interface.
  - Read&Write (readWrite). This capability supports both reading and writing.

// Device capabilities description
{
  "capabilities": [
    // Power control
    {
      "capability": "power",
      "permission": "readWrite"
    },
    // Brightness adjustment
    {
      "capability": "brightness",
      "permission": "readWrite"
    }
  ]
}
// Obtain the status state structure returned by the device list interface
{
  "state"：{
    "[capability]": {
      "[capabilityState]"：[value]
      }
   } 
}
{
  "state": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}
// Modify device state - power off
{
  "state": {
    "power": {
       "powerState": "off"
    }
  }
}

3.Web API

Type of Data

Type	Description
string	String data type. UTF8 encoded.
number	Number data type. double-precision 64-bit binary format IEEE 754
int	Integral data type.
object	Object data type. JSON-compliant object
string[]	Array of string
int[]	Array of integral
object[]	Array of object
bool	Boolean
date	Time string. String in ISO (ISO 8601 Extended Format) format: YYYY-MM-DDTHH:mm:ss.sssZ. The time zone is always UTC (Coordinated Universal Time), identified by a suffix “Z”.

Generic Response Results

Attribute	Type	Optional	Description
error	int	N	Error code:0: Success400:Parameter error401:Authentication failed500:Server exception
data	object	N	Response data body
message	string	N	Response description: When the error is equal to 0, the content is successful. When the error is not equal to 0, it is a non-empty string, and the content is an error description.

Response Example:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}



{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}

Resource List

Type	Description
Supported sound	– alert1 (Alarm Sound 1) – alert2 (Alarm Sound 2) – alert3 (Alarm Sound 3) – alert4 (Alarm Sound 4) – alert5 (Alarm Sound 5) – doorbell1 (Doorbell Sound 1) – doorbell2 (Doorbell Sound 2) – doorbell3 (Doorbell Sound 3) – doorbell4 (Doorbell Sound 4) – doorbell5 (Doorbell Sound 5) – alarm1 (Alarm Sound 1) – alarm2 (Alarm Sound 2) – alarm3 (Alarm Sound 3) – alarm4 (Alarm Sound 4) – alarm5 (Alarm Sound 5)
Supported deep	– bootComplete (System startup completed) – networkConnected (Network connected) – networkDisconnected (Network disconnected) – systemShutdown (System shutdown) -deviceDiscovered (Discover device) – system Armed (System armed enable) – system Disarmed (System armed disable) – factoryReset (Reset device)

3.1 The Gateway Function

a. Access Token

Allow users to access the token. NSPanel Pro Version ≥ 1.5.0
● Notice: The token will be cleared after device reset.
● Notice: After obtaining the token, you need to press the button again to successfully obtain a new token.

URL：/open-api/v1/rest/bridge/access_token
Method: GET
Header：
- Content-Type: application/json

Request Parameters: None

Successful data response:

Attribute	Type	Optional	Description
token	string	N	The interface access credentials are valid for a long time, please keep them properly.
app_name	string	Y	Application name description.

Condition: User trigger the < command key > and access this interface within the valid time.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Failure data response：empty Object

Conditions： The user has not triggered the < command key >, or the valid time has expired.

Status Code: 200 OK

Response Example:

{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

b. Set the Gateway

Allow authorized users to set the gateway through this interface NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/bridge/config
Method：PUT
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters:

Attribute	Type	Optional	Description
volume	int	Y	System volume. [0-100]

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

c. Get the Gateway Info

Allow authorized users to get the gateway info through this interface NSPanel Pro Version ≥ 1.7.0

URL：/open-api/v1/rest/bridge
Method： GET
Header：
- Content-Type: application/json

Request parameters: None

Successful data response:

Attribute	Type	Optional	Description
ip	string	N	ip adress
mac	string	N	mac adress
domain	string	N	local domain
fw_version	string	N	firmware version

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
    "error": 0,
    "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C",
    "domain": "NSPanelPro.local",
    "fw_version": "1.0.0"
  },
  "message": "success"
}

3.2 Screen Display Function

a. Set the Screen Brightness

Allow authorized users to set the screen brightness through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/screen/brightness
Method：PUT
Header：

Content-Type: application/json
Authorization: Bearer

Request Parameters:

Attribute	Type	Optional	Description
mode	string	N	Screen brightness mode. Optional parameters: 1. auto (Auto Mode) 2.manual (Manual Mode)
value	int	Y	Brightness value. Optional range [0,100]. It only takes effect in Manual Mode.

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

b. Set the Screen Display

Allow authorized users to set the screen display through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/screen/display
Method：PUT
Header：
- Content-Type: application/json
- Authorization: Bearer

Request parameters:

Attribute	Type	Optional	Description
auto_screen_off	ScreenOffObject	N	Auto screen off setting

ScreenOffObject Object

Attribute	Type	Optional	Description
enable	boolean	N	Whether to enable auto screen off. 1.true (enable) 2.false (disable, the screen will be always on)
duration	int	Y	Auto screen off time. Unit: second. [15 – 1800]

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.3 Hardware Function

a. Restart Gateway

Allow authorized user to restart the gateway through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/hardware/reboot
Method：POST
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters: none

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

b. Speaker Control

Allow authorized users to control the speaker through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/hardware/speaker
Method：POST
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters:

Attribute	Type	Optional	Description
type	string	N	Optional parameters: 1.play_sound (play the sound) 2.play_beep (play the beep)
sound	SoundObject	Y (N if type is play_sound.)	The sound.
beep	BeepObject	Y (N if type is play_beep.)	The beep

SoundObject Object

Attribute	Type	Optional	Description
name	string	N	The sound name. The supported values can be checked in [Resource List – Supported sound]
volume	int	N	The sound volume. [0-100]
countdown	int	N	The duration for the speaker to play the sound, and it will stop playing automatically after the time is up. Unit: second. [0,1799]

BeepObject Object

Attribute	Type	Optional	Description
name	string	N	The deep name. The supported values can be checked in [Resource List – Supported deep]
volume	int	N	The deep volume. [0-100]

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.4 Thermostat Function

a. Get the List of Thermostats

Allow users to obtain the list of Thermostats through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/thermostats
Method： GET
Header：
- Content-Type: application/json
- Authorization: Bearer

Request parameters: none

Successful data response:

Attribute	Type	Optional	Description
thermostats	ThermostatObject []	N	The list of thermostats

ThermostatObject Object

Attribute	Type	Optional	Description
tid	string	N	Thermostat ID
name	string	N	Thermostat Name
target_setpoint	TemperatureObject	Y	Thermostat Setting

TemperatureObject Object

Attribute	Type	Optional	Description
value	string	N	The temperature value. Can be set to decimal.
scale	string	N	The temperature scale. Optional parameters: c-Celsius

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {
    "thermostats": [
      {
        "tid": "thermostat id",
        "name": "thermostat name",
        "target_setpoint": {
          "value": 20,
          "scale": "c"
        }
      }
    ]
  },
  "message": "success"
}

b. Set the Specific Thermostat

Allow users to set the specific Thermostats through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/thermostats/{tid}
Method：PUT
Header：
- Content-Type: application/json
- Authorization: Bearer

Request parameters:

Attribute	Type	Optional	Description
target_setpoint	TemperatureObject	N	Set the specific thermostat target temperature. [16-31]。

TemperatureObject Object

Attribute	Type	Optional	Description
value	string	N	The temperature value. Can be set to decimal.
scale	string	N	The temperature scale. Optional parameters: c-Celsius

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.5 Device Management Function

a. Supported Device Type

Device Type	Value	NSPanel Pro Version
Plug	plug	≥ 1.5.0
Switch	switch	≥ 1.5.0
Light	light	≥ 1.5.0
Curtain	curtain	≥ 1.5.0
Door/Window Sensor	contactSensor	≥ 1.5.0
Motion sensor	motionSensor	≥ 1.5.0
Temperature sensor	temperatureSensor	≥ 1.5.0
Humidity sensor	humiditySensor	≥ 1.5.0
Temperature and humidity sensor	temperatureAndHumiditySensor	≥ 1.5.0
Water leak detector	waterLeakDetector	≥ 1.5.0
Smoke detector	smokeDetector	≥ 1.5.0
Wireless button	button	≥ 1.5.0
Camera	camera	≥ 1.5.0
General sensor	sensor	≥ 1.5.0

b. Supported Device Capabilities

Name	Description	Capability&Permission Example	Attribute(Status)	Protocol(Status inquiry&Control command)
power ≥ 1.5.0	Power control	[ { “capability”: “power”, “permission”: “readWrite” }]	{ “powerState”: “on”, //The field powerState indicates the power on/off state, which is required. string type, ”on“ means on, ”off“ means off, ”toggle“ means reverse.}	Turn on：{ “powerState”: “on”}Turn off：{ “powerState”: “off”}
toggle ≥ 1.5.0	Toggle control	[ // Single toggle example { “capability”: “toggle”, “permission”: “readWrite”, “name”: “1” }, // Multiple toggle example[ { “capability”: “toggle”, “permission”: “readWrite”, “name”: “1” }, { “capability”: “toggle”, “permission”: “readWrite”, “name”: “2” }]	{ “toggleState”: “on”, // The field “toggleState” indicates the toggle state of the {name} attribute of {device_id}. Required. String type. “on” means open, “off” means close, “toggle” means reverse.}	toggle format is special{ [capability] :{ [toggle-name]：{ [toggleState]:[value] } }}toggle 1 on, toggle 2 off{ “toggle”: { “1”: { “toggleState”: “on” }, “2”: { “toggleState”: “off” } }}
brightness ≥ 1.5.0	Brightness Control	[ { “capability”: “brightness”, “permission”: “readWrite” }]	{ “brightness”: 100, // The field “brightness” indicates the percentage of brightness. Int type. An integer with a value range of 0~100.}	0 is the darkest and 100 is the brightest. Set the brightness to 80%. { “brightness”: { “brightness”: 80, }}
color-temperature ≥ 1.5.0	Color temperature control	[ { “capability”: “color-temperature”, “permission”: “readWrite” }]	{ “colorTemperature”: 100, // 字段 “colorTemperature” Indicates the percentage of color temperature. Int type. An integer with a value range of 0~100. 0 means warm light, 50 means neutral light, and 100 means cold light.}	Set the Color temperature to 80%. { “color-temperature”: { “colorTemperature”: 50 }}
color-rgb ≥ 1.5.0	Color control	[ { “capability”: “color-rgb”, “permission”: “readWrite” }]	{ “red”: 255, // The field “red” represents red in the RGB color space. Required. Int type. An integer with a value range of 0~255. “green”: 0, // The field “green” represents green in the RGB color space. Required. Int type. An integer with a value range of 0~255. “blue”: 255, // The field “blue” represents blue in the RGB color space. Required. Int type. An integer with a value range of 0~255.}	Set the color.{ “color-rgb”: { “red”: 255, “green”: 0, “blue”: 255, }}
percentage ≥ 1.5.0	Percentage control	[ { “capability”: “percentage”, “permission”: “readWrite” }]	{ “percentage”: 100, // The field “percentage” represents a percentage of a certain degree, and the field percentageDelta can be selected as one of the two. int type. An integer with a value range of 0~100.}	Set to 40%{ “percentage”: { “percentage”: 40 }}
motor-control ≥ 1.5.0	Motor control	[ { “capability”: “motor-control”, “permission”: “readWrite” }]	{ “motorControl”: “stop”, // The field “motor-control“ indicates the open or close state of the motor。 Required. String type. Optional values, “open” (open), “close” (close), “stop” (stop), “lock” (lock).}	Turn on the motor{ “motor-control”: { “motorControl”: “open” }}
motor-reverse ≥ 1.5.0	Motor reverse	[ { “capability”: “motor-reverse”, “permission”: “readWrite” }]	{ “motorReverse”: true, // The field “motor-reverse” indicates the forward and reverse setting of the motor. Required. boolean type. true means forward rotation, false means reverse rotation.}	Set the motor reverse{ “motor-reverse”: { “motorReverse”: false }}
startup ≥ 1.5.0	Power on state (Power Supply)	[ { “capability”: “startup”, “permission”: “readWrite” }]	{ “startup”: “on” // String type. Required. Optional values, “on” (power on) ，“stay“ (stay power on)，”off“ (power off)}	Set the power on state to always stay on when powered on{ “startup”: { “startup”: “on” }}
startup ≥ 1.5.0	Toggle power on state (can use with toggle)	[ { “capability”: “startup”, “permission”: “readWrite”, “components”: [ //Components that support power on retention. If the device with the toggle sub-channel needs to support power on retention, this field is mandatory. In particular, the toggle capability supports separate power-on retention settings. For details, see the update protocol of toggle. // toggle 1 power on state { “capability”: “toggle”, // String type. Required. Represents the name of the component capability that supports power-on retention. Only “power” and “toggle” are supported. “name”: “1”, // The field “name” indicates the attribute name that can be toggled. Required. String type. Only uppercase and lowercase letters and numbers are allowed. Taking the multi-channel switch as an example, it should be the channel number, that is, 1, 2, 3, 4 } ] }]	{ “startup”: “on” // String type. Required. Optional values, “on” (power on) ，“stay“ (stay power on)，”off“ (power off)}	When channel 1 power on, the power state is always on{ “toggle”: { “1”: { “startup”: “on” } }}
camera-stream ≥ 1.5.0	Camera stream	{ “capability”: “camera-stream”, // The field “capability” indicates the name of the specific function. Rrequired. String type. camera-stream indicates the video streaming capability of the camera. “permission”: “read”, // The field “permission” indicates the use of specific functions. Required. String type. Optional values: “read” (readable), “write” (writable), “readWrite” (readable and writable)。 “configuration”: { “streamUrl”: “rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01”, //stream url. String type. Required. } }	/	{ “camera-stream”: { “configuration”: { “streamUrl”: “rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01”, // stream url. String type. Required. } }}
motor-clb ≥ 1.5.0	Motor calibration detection	[ { “capability”: “motor-clb”, “permission”: “read” }]	{ “motorClb”: “calibration”, // The field “motor-clb” indicates that the motor has been calibrated Required. String type, normal means normal mode (calibrated), calibration means it is being calibrated.}	The motor is being calibrated.{ “motor-clb”: { “motorClb”: “calibration” }}
detect ≥ 1.5.0	State detection	[ { “capability”: “detect”, “permission”: “read” }]	{ “detected”: true, // The field “detected” indicates the current detection result. Required. Boolean type, true indicates that the condition is detected, false indicates that the condition is not detected.}	The current state is the result detected.{ “detect”: { “detected”: true }}
humidity ≥ 1.5.0	Humidity detection	[ { “capability”: “humidity”, “permission”: “read”, “configuration”: { // Configuration items, optional “range”: { // Percentage range configuration. Optional. Default range [0-100]. “min”: 0, // Minimum value, int type. Required. Range 0-100, must be less than max. “max”: 100 // Maximum value, int type. Required. Range 0-100, must be greater than min. } } }]	{ “humidity”: 50, // The field “humidity” indicates the current relative humidity (percentage). Required. Int type. An integer with a value range of 0~100.}	Current humidity is 20{ “humidity”: { “humidity”: 20 }}
temperature ≥ 1.5.0	Temperature detection	[ { “capability”: “temperature”, “permission”: “read”, “configuration”: { // Configuration items, optional “range”: { // Temperature range configuration. Optional. “min”: -40, // Minimum value, int type. Required. “max”: 80 //Maximum value, int type. Required. } } }]	{ “temperature”: 26.5, // The field “temperature” indicates the current temperature. Required. Number type. The unit is Celsius.}	Current temperature is 20 Celsius{“temperature”: {“temperature”: 20}}
battery ≥ 1.5.0	Remaining battery detection	[{ “capability”: “battery”, “permission”: “read” }]	{ “battery”: 95, // The field “battery” indicates the percentage of remaining battery power. Required. Int type. An integer with a value range of -1~100. -1 means that the battery level is unknown.}	Current remaining power is 40.{ “battery”: { “battery”: 40 }}
press ≥ 1.5.0	Press detection	[ { “capability”: “press”, “permission”: “read” }]	{ “press”: “singlePress”, // The field “press” indicates the method of pressing the button. Required. String type. ptional values: “singlePress” (single-click/single short press), “doublePress” (double-click/two consecutive short presses), “longPress” (long press).}	A single click was detected{ “press”: { “press”: “singlePress” }}
rssi ≥ 1.5.0	Wireless signal strength detection	[ { “capability”: “rssi”, “permission”: “read” }]	{ “rssi”: -65, // The field “rssi” indicates the wireless signal strength (received signal strength indication). Required. int type. The unit is dBm, and the optional value is a negative integer.}	{ “rssi”: {“rssi”: -65 }}
thermostat-mode-detect ≥ 1.10.0	Thermostat mode detection There are two detection types: 1. Temperature detection (temperature) 2. Humidity detection Detection options: 1. Minimum value detection: lowerSetpoint 2. Highest value detection: upperSetpoint Supported modes: 1. supportedModes	[ { “capability”: “thermostat-mode-detect”, // Temperature control mode detection “permission”: “readWrite”, “name”: “humidity”, // Temperature control detection type, String type, required. Optional parameters, humidity (humidity detection), temperature (temperature detection) “configuration”: { // required “supported”: [ // Supported detection setting conditions, required. { “name”: “lowerSetpoint”, // The detection value should remain above the set value. There must be at least one lowerSetpoint and upperSetpoint. “value”: { // Detection range, optional. If there are preset conditions, write them. “value”: 68.0, // Temperature or humidity value, required. “scale”: “f” // Temperature unit, required when name=temperature. c (Celsius), f (Fahrenheit) } }, { “name”: “upperSetpoint”, // The detection value should remain below the set value. There must be at least one lowerSetpoint and upperSetpoint. “value”: { // Detection range, optional. If there are preset conditions, write them. “value”: 68.0, // Temperature or humidity value, required. “scale”: “f” // Temperature unit, required when name=temperature. c (Celsius), f (Fahrenheit) } } ], “supportedModes”: [ // Supported modes, optional. “COMFORT”, “COLD” //Supported mode id, optional parameters, COMFORT (comfort mode), COLD (cold mode), HOT (hot), DRY (dry), WET (humid) ] } } ]	{ “mode”: “COMFORT”, // Supported mode id, optional parameters, COMFORT (comfort mode), COLD (cold mode), HOT (hot), DRY (dry), WET (humid) }	Format: { [capability] :{ [mode name]: { mode:[value] } } } Example: { “thermostat-mode-detect “: { “humidity”: { “mode”: “COMFORT” } } }
power-consumption ≥ 1.11.0	Power Consumption	[ { “capability”: “power-consumption”, “permission”: “readWrite”, “configuration”: { “resolution”: 3600, // Time interval for counting power, unit is second, number type, required. The value range is greater than or equal to 3600, that is, more than 1 hour. “timeZoneOffset”: 0 //The time zone offset of power statistics, type number, required. The value range is [-12.0 ~ 14.0]. “queryCommandOnly”: true // Only supports query, does not update status, boolean type, required. Currently only true is supported. } } ]	// Start/stop real-time statistics { “rlSummarize”: true, // Start/stop real-time statistics, Boolean type, required. } //Query the power statistics by time range { “type”: “summarize”, // Statistics type, String type, required. Optional parameters, “rlSummarize” (real-time statistical summary), “summarize” (current summary). “timeRange”: { // The time range of summary, required when type=”summarize”. “start”: “2020-07-05T08:00:00Z”, //Start time for power statistics, String type, required. “end”: “2020-07-05T09:00:00Z” // End time of power statistics, String type, optional. If there is no end, it indicates the current time. } } // Statistical power results within the response time range { “type”: “summarize”, // Statistics type, String type, required. Optional parameters, “rlSummarize” (real-time statistical summary), “summarize” (current summary). “rlSummarize”: 50.0, // Indicates the total power consumption, the unit is 0.01kwh, optional. Number type. “electricityIntervals”: [ // Divide into multiple statistical records according to configuration.resolution, optional. This field does not exist when type=”rlSummarize”. { “usage”: 26.5, // The field power-consumption indicates electricity consumption, the unit is 0.01kwh, required. number type. “start”: “2020-07-05T08:00:00Z”, //Start time, date type, required. “end”: “2020-07-05T09:00:00Z” //End time, date type, required. If the interval between end and start is less than resolution, all reported records are considered invalid. }, { “usage”: 26.5, // The field power-consumption indicates electricity consumption, the unit is 0.01kwh, required. number type. “start”: “2020-07-05T09:00:00Z”, //Start time, date type, required. “end”: “2020-07-05T10:00:00Z” //End time, date type, required. If the interval between end and start is less than resolution, all reported records are considered invalid. } ] }	{ “power-consumption “: { “rlSummarize”: true } } { “power-consumption “: { “type”: “summarize”, “timeRange”: { “start”: “2020-07-05T08:00:00Z”, “end”: “2020-07-05T09:00:00Z” } } }
illumination-level ≥ 1.11.0	Illumination Level	[ { “capability”: “illumination-level”, “permission”: “read” } ]	{ “level”: “brighter”, // Brightness level, String type, required. Optional parameters, “brighter” (brighter), “darker” (darker) }	{ “illumination-level”: { “level”: “brighter” } }
thermostat ≥ 1.11.0	Thermostat Feature	[ { “capability”: “thermostat”, “permission”: “read”, “name”: “adaptive-recovery-status” // Temperature control adaptive status }, { “capability”: “thermostat”, “permission”: “readWrite”, “name”: “thermostat-mode”, “configuration”: { // required “supportedModes”: [ // Built-in modes “MANUAL”, “AUTO”, “ECO” ] } }, ]	{ “targetSetpoint”: 30, // Target temperature, number type, unit is the same as scale, see configuration.temperature for the range } { “adaptiveRecoveryStatus”: “HEATING”, // Temperature control adaptive status, String type, optional values: “HEATING” (heating), “INACTIVE” (inactive) } { “thermostatMode”: “MANUAL”, // Temperature control operating mode, String type, see configuration.supportedModes for optional values. }	{ “thermostat”: { “adaptive-recovery-status”: { “adaptiveRecoveryStatus”: “HEATING” } } } { “thermostat”: { “thermostat-mode”: { “thermostatMode”: “MANUAL” } } }
thermostat-target-setpoint ≥ 1.11.0	Thermosta Target Setpoint	[ { “capability”: “thermostat-target-setpoint”, “permission”: “readWrite”, “name”: “manual-mode”, // component name, String type, “manual-mode” represents the target temperature in manual mode of the temperature control device “configuration”: { “temperature”: { “min”: 4, “max”: 35, “increment”: 0.5, // Temperature adjustment step size, the unit is the same as scale. required. “scale”: “c” // Temperature unit, required. c (Celsius), f (Fahrenheit) }, “mappingMode”: “MANUAL” // Mapping mode: thermostat-mode.MANUAL } }, { “capability”: “thermostat-target-setpoint”, “permission”: “read”, “name”: “auto-mode”, // Component name, String type, “auto-mode” represents the target temperature in the automatic mode of the temperature control device “configuration”: { “temperature”: { // Temperature configuration item “min”: 4, “max”: 35, “increment”: 0.5, // Temperature adjustment step size, the unit is the same as scale. required. “scale”: “c” // Temperature unit, required. c (Celsius), f (Fahrenheit) }, “mappingMode”: “AUTO”, // Mapping mode: thermostat-mode.AUTO “weeklySchedule”: { // Schedule configuration items “maxEntryPerDay”: 2 // Maximum number of segments per day “Monday”: [{ “startTimeInMinutes”: 440, //Start time, expressed in minutes, type int. Such as 7:20 = 7 * 60 + 20 = 440 “upperSetpoint”: 36.5, // The maximum value of the target temperature, number type. There must be at least one lowerSetpoint and upperSetpoint. “lowerSetpoint”: 20, //The lowest value of the target temperature, number type. There must be at least one lowerSetpoint and upperSetpoint. }, { “startTimeInMinutes”: 900, //Start time, expressed in minutes, int type. For example, 15:00 = 15 * 60 = 900 “upperSetpoint”: 26.5, // The maximum value of the target temperature, number type. There must be at least one lowerSetpoint and upperSetpoint. “lowerSetpoint”: 21, //The lowest value of the target temperature, number type. There must be at least one lowerSetpoint and upperSetpoint. }], “Tuesday”: […], “Wednesday”: […], “Thursday”: […], “Friday”: […], “Saturday”: […], “Sunday”: […], } } }, { “capability”: “thermostat-target-setpoint”, “permission”: “readWrite”, “name”: “eco-mode”, // Component name, String type, “eco-mode” represents the target temperature in the energy-saving mode of the temperature control device “configuration”: { “temperature”: { “min”: 4, “max”: 35, “increment”: 0.5, // Temperature adjustment step size, the unit is the same as scale. required. “scale”: “c” // Temperature unit, required. c (Celsius), f (Fahrenheit) }, “mappingMode”: “ECO” // Mapping mode: thermostat-mode.ECO } } ]	{ “targetSetpoint”: 30, // Target temperature, number type, unit is the same as scale, see configuration.temperature for the range }	{ “thermostat-target-setpoint”: { “manual-mode”: { “targetSetpoint”: 30 }, “auto-mode”: { “targetSetpoint”: 30 } } }
fault ≥ 1.11.0	Fault Notification Capability	[ { “capability”: “fault”, “permission”: “read” } ]	{ “fault”: “reasonCode1”, // Fault error code, String type, customized. }	{ “fault”: { “fault”: “reasonCode1” } }

c. Tags Description

The special key toggle is used to set the name of the toggle subcomponent.

{
    "toggle": {
        '1': 'Chanel1',
        '2': 'Chanel2',
        '3': 'Chanel3',
        '4': 'Chanel4',
    },
}

The special key temperature_unit is used to set the temperature unit.

{
    "temperature_unit":'c' // c-Celsius; f-Fahrenheit
}

d. Special Error Code and Description

Error Code	Description	NSPanel Pro Version
110000	The sub-device/group corresponding to the id does not exist	≥ 1.5.0
110001	The gateway is in the state of discovering zigbee devices	≥ 1.5.0
110006	Failed to update device status	≥ 1.5.0

e. Search for Sub-device

Allow authorized users to enable or disable gateway search for sub-devices through this interface.

NSPanel Pro Version ≥ 1.5.0

💡Note: Only supports searching for Zigbee sub-devices now.
💡Note: Zigbee sub-devices will be added automatically after searching. Do not need to use the “Manually Add Sub-devices” interface

URL：/open-api/v1/rest/devices/discovery
Method: PUT
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters:

Attribute	Type	Optional	Description
enable	boolean	N	true (Start paring); false (Pause pairing)
type	string	N	Searching Type: Zigbee

Successful data response: empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Manually Add the Sub-device

Allow authorized users to add a single sub-device through this interface. NSPanel Pro Version ≥ 1.5.0

Note: Only RTSP Camera and ESP32 Camera are supported now

URL：/open-api/v1/rest/devices
Method：POST
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters:

Attribute	Type	Optional	Description
name	string	N	Sub-device name
display_category	string	N	Device Type. Only supports the camera.
capabilities	CapabilityObject[]	N	Capability list. When display_category = camera, capabilities only include camera-stream capabilities.
protocol	string	N	Device protocol. RTSP; ESP32-CAM
manufacturer	string	N	Manufacturer.
model	string	N	Device model
firmware_version	string	N	Device firmware version

CapabilityObject Object

Attribute	Type	Optional	Description
capability	string	N	Capability name. Only support “camera-stream”
permission	string	N	Device permission. Only supports read.
configuration	CameraStreamConfigurationObject	Y	Camera stream configuration.

CameraStreamConfigurationObject Object

Attribute

Type

Optional

Description

stream_url

string

N

Stream url，<schema>://<hostname>:<port>/<username>:<password>@<service_path>，e.g.: rtsp://admin:123456@192.168.10.115:554/streaming/channel01

schema optional：

· rtsp

· http （For ESP32-Camera）

Note: Some cameras don’t have account numbers and passwords, so you can leave the username and password blank. |

Successful data response:

Attribute	Type	Optional	Description
serial_number	string	N	Device unique serial number

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}

Failure data response: empty Object

Condition：
1. Camera stream address access error (format error, authorization failure, network exception, etc.)
2. Device already exists
3. If a single device fails to add, it returns all devices fail to add.

Status Code: 200 OK
Error code：
● 110009 Camera IP address error
● 110010 Camera access authorization error
● 110011 Camera stream address error
● 110012 The Camera video encoding does not support
● 110013 Device already exists

Response Example:

{
"error": 110009,
"data": {},
"message": "camera ip access failed"
}

g. Get List of Sub-devices

Allow authorized users to obtain the list of gateway sub-device through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/devices
Method: GET
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters: none

Successful data response:

Attribute	Type	Optional	Description
device_list	ResponseDeviceObject[]	N	Device list

ResponseDeviceObject Object

Attribute	Type	Optional	Description
serial_number	string	N	Device unique serial number
third_serial_number	string	“N” when a third-party device is connected, otherwise “Y”	Third-party device unique serial number
service_address	string	“N” when a third-party device is connected, otherwise “Y”	Third-party service address
name	string	N	Device name, if it is not renamed, will be displayed by the front end according to the default display rules.
manufacturer	string	N	Manufacturer
model	string	N	Device model
firmware_version	string	N	Firmware version. Can be an empty string.
hostname	string	Y	Device hostname
mac_address	string	Y	Device mac address
app_name	string	Y	The name of the application to which it belongs. If the app_name is filled in when obtaining the open interface certificate, then all subsequent devices connected through the certificate will be written into this field.
display_category	string	N	Device category
capabilities	CapabilityObject[]	N	Device capabilities
protocol	string	“N” when a third-party device is connected, otherwise “Y”	Device protocol: zigbee, onvif, rtsp, esp32-cam
state	object	Y	Device state object. For state examples of different capabilities, please check 【Support Device Capabilities】
tags	object	Y	JSON format key-value, custom device information. The function is as follows:- Used to store device channels- Used to store temperature units- Custom information for other third-party devices
online	boolean	N	Online status: True for onlineFalse is offline
subnet	boolean	Y	Whether it is in the same subnet as the gateway

CapabilityObject Object

💡Note: Please check the Examples of Supported Device Capabilities for [Supported Device Capabilities].

Attribute	Type	Optional	Description
capability	string	N	Ability name. For details, check [Supported Device Capabilities]
permission	string	N	Capability permission. Possible values are “read” (readable), “write” (writable), “readWrite” (readable and writable).
configuration	object	Y	Capability configuration information. Currently camera-stream is used, check [Supported Device Capabilities]
name	string	Y	The name field in toggle. The sub-channel number used to identify multi-channel devices. For example, if name is 1, it means channel 1.

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "third_serial_number": "third_serial_number",
        "name": "My Device",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocol": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}

h. Update Specified Device Information or State

Allow authorized users to modify the basic information of sub-device and issue control commands through this interface.

NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/devices/{serial_number}
Method： PUT
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request parameters:

Attribute	Type	Optional	Description
name	string	Y	Device name
tags	object	Y	JSON format key-value, custom device information.
state	object	Y	Device state object. For state examples of different capabilities, please check [Support Device Capabilities]
configuration	object	Y	Capability configuration information, currently only the camera_stream capability supports modification.
capabilities	CapabilityObject []	Y	Capability configuration information, all capabilities that support configuration configuration can be modified. Note that permission cannot be changed.

Successful data response:

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Error Code:

110000 The sub-device/group corresponding to the id does not exist
110006 Failed to update device status
110019 Access to third-party device service address failed

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

import axios from 'axios';
const serial_number = 'serial_number';
const access_token = 'access_token';
(async function main() {
    // turn on device
    await axios({
        url: `http://<domain name or ip address>/open-api/v1/rest/devices/${serial_number}`,
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${access_token}`
        },
        data: {
            state: {
                power: {
                    powerState: 'on'
                }
            }
        }
    });
})()

i. Delete Sub-device

Allow authorized users to delete sub-devices through this interface. NSPanel Pro Version ≥ 1.5.0

URL：/open-api/v1/rest/devices/{serial_number}
Method： DELETE
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request Parameters: none

Successful data response:

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Response Example:

{
  "error": 0,
  "data": {},
  "message": "success"
}

j. Query Device Status Information

NSPanel Pro Version ≥ 2.0.0

URL：/open-api/v1/rest/devices/{serial_number}/query-state/power-consumption
Method： POST

Request parameters:

Attribute	Type	Optional	Description
type	string	N	Summarize type “rlSummarize” – real-time statistical summary “summarize” – Summarize the current
timeRange	object	Required when type is “summarize”	Summarize time range
start	date	N	Summarize power start time
end	date	Y If not filled in, the current time will be defaulted.	Summarize power end time

Request Example:

// Example: Summarize the power from 2020-07-05T08:00:00Z to 2020-07-05T09:00:00Z
{
    “type”: “summarize”,
    “timeRange”: {
        “start”: “2020-07-05T08:00:00Z”,
        “end”: “2020-07-05T09:00:00Z”
    }
}

// Example: Summarize the power consumption from 2020-07-05T08:00:00Z to the current time
{
    “type”: “summarize”,
    “timeRange”: {
        “start”: “2020-07-05T08:00:00Z”
    }
}

// Example: real-time statistics summary
{
“type”: “rlSummarize”
}

Successful data response:

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Error Code:

● 110000: The subdevice/group corresponding to the id does not exist
● 110005: The device is offline
● 110021: Failed to query device status

Attribute	Type	Description
type	string	Summarize type “rlSummarize” – real-time statistical summary “summarize” – Summarize the current
rlSummarize	Int	Total electricity consumption, unit is 0.01kwh
electricityIntervals	Array<Object>	Statistical record list, this field exists when type=”summarize” Divide into multiple statistical records according to configuration.resolution.

electricityIntervals parameter description:

Attribute	Type	Description
usage	string	Electricity consumption, unit is 0.01kwh
start	String	Summarize start time
end	String	Summarize end time

Response Example:

// Example 1: Battery power from 2020-07-05T08:00:00Z to 2020-07-05T10:00:00Z
{
    “data”:{
        “type”: “summarize”,
        “electricityIntervals”: [
            {
                “usage”: 26.5,
                “start”: “2020-07-05T08:00:00Z”,
                “end”: “2020-07-05T09:00:00Z”
            },
          {
                “usage”: 26.5,
                “start”: “2020-07-05T09:00:00Z”,
          “end”: “2020-07-05T10:00:00Z”
            }
        ]
    }
}

//Example 2: Real-time power statistics
{
    “data”:{
        “type”: “rlSummarize”,
        “rlSummarize”: 50.0
    }
}

4. Third-party Device Access

4.1 Access Instruction

Device Access

Third-party gateway Access

Access steps

Determine the classification of the device in the gateway. The detail please check the [Supported Device Type].
Determine the capabilities that the device can access. The detail please check the [Supported Device Capabilities].
Request the [Discovery Request] interface to add the device to the gateway.
1. Attention: You need to provide the service address for receiving the instructions issued by the gateway, which is used to receive the device control instructions issued by the gateway.
If the status of the third-party device changes, you need to call the [Device States Change Report] interface to send the latest status back to the gateway.
After adding, the third-party device will appear in the Device List, with most of the functions of the gateway (other non-third-party devices). The common open interfaces related to the device can be used normally.

Select the appropriate device category. The classification will affect the final display result of the UI after the device is connected to the gateway.
Choose the right device capability. The capability list will determine the status of the device state protocol.

Program Process

a. Device Access

b. Third-party Gateway Access

4.2 Access Example

Switch, Plug

Sync third-party devices

Request Example

// Request
URL：/open-api/v1/rest/thirdparty/event
Method：POST
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body:
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "firmware version",
          "service_address": "http://192.168.31.14/webhook"
        }
      ]
    }
  }
}

Response Example

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "serial number"
      }
    ]
  }
}

Report device status

Request Example

URL：/open-api/v1/rest/thirdparty/event
Method：POST
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body:
{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Response Example

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

Report offline/online

Request Example

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Response Example

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

Receive the instructions about the gateway control device

Request Example

URL：<service address>
Method：POST
Header：
  Content-Type: application/json
B
{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

Response Example

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

Query device

Request Example

URL：/open-api/v1/rest/devices
Method：GET
Header：
  Content-Type: application/json
  Autorization: Bearer  <token>
Body: 无

Response Example

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number",
        "name": "my plug",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "firmware version",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}

4.3 Web API

Third-Party Request Gateway Interface

Request Format

Allow authorized users to send event requests to the gateway through this interface.

URL：/open-api/v1/rest/thirdparty/event
Method：POST
Header：
- Content-Type: application/json
- Authorization: Bearer <token>

Request Parameters:

Attribute	Type	Optional	Description
event	EventObject	N	Request event object structure information

EventObject Object

Attribute	Type	Optional	Description
header	HeaderObject	N	Request header structure information
endpoint	EndpointObject	Y	Request endpoint structure informationNote: This field is empty when sync a new device list.
payload	PayloadObject	N	Request payload structure information

HeaderObject Object

Attribute	Type	Optional	Description
name	string	N	Request name. optional parameter: DiscoveryRequest: Sync new devices DeviceStatesChangeReport: Device status update report DeviceOnlineChangeReport: Device online status report
message_id	string	N	Request message ID, UUID_V4
version	string	N	Request protocol version number. Currently fixed at 1

EndpointObject Object

Attribute	Type	Optional	Description
serial_number	string	N	Device unique serial number
third_serial_number	string	N	Third-party device unique serial number
tags	object	Y	JSON format key-value, custom device information. [Device Management Function] – [Tags Description]

PayloadObject Object:

According to the different header.name have different request structure.

Response Format

Status Code: 200 OK

Response parameters:

Attribute	Type	Optional	Description
header	HeaderObject	N	Response header structure information
payload	PayloadObject	N	Response payload structure information

HeaderObject Object

Attribute	Type	Optional	Description
name	string	N	Response header name. optional parameters:Response: Successful response ErrorResponse: Error response
message_id	string	N	Response header message ID, UUID_V4. Pass in the request message header.message_id here*If the request input parameter lacks message_id, this field will be an empty string when responding.
version	string	N	– Request protocol version number. Currently fixed at 1.

Successful response–PayloadObject Object：

Depending on the request type, the response structure is different. For details, please refer to the specific request instruction document.

Failure response–PayloadObject Object：

Attribute	Type	Optional	Description
type	string	N	Error Type: INVALID_PARAMETERS: Parameter error INTERNAL_ERROR :Service internal error
description	string	N	Error description

DiscoveryRequest Sync a new device list

NSPanel Pro Version ≥ 1.5.0

Note: After the device is synchronized to the gateway, it is online by default, that is, online=true. Subsequent online changes are completely dependent on synchronization with the third party through the DeviceOnlineChangeReport interface.

Request parameters:

EndpointObject Object：

None

PayloadObject Object：

Attribute	Type	Optional	Description
endpoints	EndpointObject[]	N	Device List

EndpointObject Object:

Attribute	Type	Optional	Description
third_serial_number	string	N	Third-party device unique serial number
name	string	N	Device name
display_category	string	N	Device Category. See the [Supported Device Type] for details. *Three-party devices don’t support adding cameras now.
capabilities	CapabilityObject[]	N	Capabilities list
state	object	N	Initial state information
manufacturer	string	N	Manufacturer
model	string	N	Device model
tags	object	Y	JSON format key-value, custom device information:Be used to store device channelsBe used to store temperature unitsOther third-party custom data
firmware_version	string	N	Firmware version
service_address	string	N	Service address. Such as http://192.168.31.14/service_address

Example of Request :

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "firmware version",
          "service_address": "<service address>"
        }
      ]
    }
  }
}

Response parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
endpoints	EndpointObject[]	N	Device list

EndpointObject Object:

Attribute	Type	Optional	Description
serial_number	string	N	Device unique serial number
third_serial_number	string	N	Third-party device unique serial number

Example of a correct response:

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}

Example of an error response:

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook cannot be empty" 
  }
}

DeviceStatesChangeReport Device status update report

NSPanel Pro Version ≥ 1.5.0

Note: Repeated status reports may falsely trigger the associated scene.

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
state	object	N	Devicce state, See [Supported device cabilities] for detail

Example of Request :

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Response parameters:

PayloadObject Object: Empty Object

Example of a successful response:

"header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

DeviceOnlineChangeReport Device online status report

NSPanel Pro Version ≥ 1.5.0

Note: Repeated status reports may falsely trigger the associated scene.

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
online	boolean	N	Device online status true: Online false: Offline

Example of Request :

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Response parameters:

PayloadObject Object: Empty Object

Example of a successful response:

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Device Information Update Report

NSPanel Pro Version ≥ 1.5.0

Note: Repeated status reports may falsely trigger the associated scene.

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
capabilities	CapabilityObject[]	N	Capability list. See the Supported Device Capabilities section for details.
tags	object	Y	json format key-value, customized device information. ● Can be used to store device channels ● Can be used to store temperature units ● Other third-party custom data

Example of Request :

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "power",
          "permission": "read"
        }
      ]
    }
  }
}

Response parameters:

PayloadObject Object: Empty Object

Example of a successful response:

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

Gateway sends the instruction interface through the device service address

Note:

The three parties need to respond to the gateway’s request within 3s. Otherwise, the gateway will judge the command processing timeout.
If the third-party service is offline, the gateway will set the device to an offline state, and the third-party service needs to report the device state (DeviceStatesChangeReport) or the online state (DeviceOnlineChangeReport) before returning to the online state. NSPanel Pro Version ≥ 1.5.0

Request format

Gateway sends instructions to the third-party through the device service address interface.

URL：<service address>
Method： POST
Header：
- Content-Type: application/json

Request parameters:

Attribute	Type	Optional	Description
directive	DirectiveObject	N	Directive object structure information

DirectiveObject Object

Attribute	Type	Optional	Description
header	HeaderObject	N	Request header structure information
endpoint	EndpointObject	N	Request endpoint structure information
payload	PayloadObject	N	Request payload structure information

HeaderObject Object

Attribute	Type	Optional	Description
name	string	N	Request name. Optional parameters:UpdateDeviceStates: Update device states
message_id	string	N	Request message ID, UUID_V4
version	string	N	Request protocol version number. Currently fixed at 1.

EndpointObject Object

Attribute	Type	Optional	Description
serial_number	string	N	Device unique serial number
third_serial_number	string	N	Third-party device unique serial number
tags	object	N	JSON format key-value, custom device information. [Device Management Function] – [Tags Description]

Example of Request :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Response format

HTTP Status Code: 200 OK

HTTP Response Attribute：

Attribute	Type	Optional	Description
event	EventObject	N	Response event structure information

EventObject Object

Attribute	Type	Optional	Description
header	HeaderObject	N	Request header structure information
payload	PayloadObject	N	Request payload structure information

HeaderObject Object

Attribute	Type	Optional	Description
name	string	N	Response header name. Optional parameter: UpdateDeviceStatesResponse: Update device states response ErrorResponse: Error response
message_id	string	N	Response header message ID, UUID_V4. Pass in the request message header.message_id here
version	string	N	Request protocol version number. Currently fixed at 1.

Successful response–PayloadObject Object：

Depending on the request type, the response structure is different. For details, please refer to the specific request instruction document.

Failure response–PayloadObject Object：

Attribute	Type	Optional	Description
type	string	N	Error type:- ENDPOINT_UNREACHABLE: Device is unreachable or offline- ENDPOINT_LOW_POWER: Device is in a low battery state and cannot be controlled- INVALID_DIRECTIVE: Command issued by the gateway is abnormal- NO_SUCH_ENDPOINT: Device doesn’t exist- NOT_SUPPORTED_IN_CURRENT_MODE: Current mode is not supported- INTERNAL_ERROR: Service internal error

Conditions: The request parameters are legal.

Status Code: 200 OK

Response parameters:

Successful response

Failure response

UpdateDeviceStates Updates Devices States

NSPanel Pro Version ≥ 1.5.0

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
state	object	N	Devicce state, See [Supported device cabilities] for detail.

Example of Request :

 "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

Response parameters:

PayloadObject Object： empty Object

Example of Successful Response

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

ConfigureDeviceCapabilities Configure Device Capabilities

NSPanel Pro Version ≥ 1.10.0

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
capabilities	CapabilityObject[]	N	Capability list. See the Supported Device Capabilities section for details. Note that the permission field cannot be changed, just pass in the same value during synchronization.

Example of Request :

  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
      {
        "capability": "thermostat-mode-detect", // Thermostat mode detect
        "permission": "readWrite",
        "name": "humidity", // Temperature control detection type, String type, required. Optional parameters, humidity (humidity detection), temperature (temperature detection)
        "configuration": { // Required.
          "supported": [ // Supported detection setting conditions, required.
          {
            "name": "lowerSetpoint", // The detection value should remain above the set value. There must be at least one lowerSetpoint and upperSetpoint.
            "value": { // Detection range, optional. If there are preset conditions, write them.
              "value": 68.0, // Temperature or humidity value, required.
              "scale": "f" // Temperature unit, required when name=temperature. c (Celsius), f (Fahrenheit)
             }
           },
           {
              "name": "upperSetpoint", // The detection value should remain below the set value. There must be at least one lowerSetpoint and upperSetpoint.
              "value": { // Detection range, optional. If there are preset conditions, write them.
                "value": 68.0, // Temperature or humidity value, required.
                "scale": "f" // Temperature unit, required when name=temperature. c (Celsius), f (Fahrenheit)
              }
            }
          ],
          "supportedModes": [ // Supported modes, optional.
            "COMFORT", 
            "COLD" // Supported mode id, optional parameters, COMFORT (comfort mode), COLD (cold mode), HOT (hot), DRY (dry), WET (humid)
            ]
          }
        }
      ]
    }
  }
}

Response parameters:

PayloadObject Object： empty Object

Example of Successful Response

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates Query device status

NSPanel Pro Version ≥ 2.0.0

Request parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
state	Object	N	Device status object. For state examples of different capabilities, please see [Supported Device Capabilities].

Example of Request :

{
    “directive”: {
        “header”: {
            “name”: “QueryDeviceStates”,
            “message_id”: “Unique identifier, preferably a version 4 UUID”,
        “version”: “1”
    },
    “endpoint”: {
        “serial_number”: “serial_number”,
        “third_serial_number”: “third_serial_number”
    },
        “payload”: {
        “state”: {
            “power-consumption”: {
                “type”: “summarize”, // Statistics type, String type, required. Optional parameters, “rlSummarize” (real-time statistical summary), “summarize” (current summary).
                “timeRange”: {
                      “start”: “2020-07-05T08:00:00Z”, //Start time for power statistics, date type, required.
                      “end”: “2020-07-05T09:00:00Z” // The end time of power statistics, date type, required.
                    }
                }
            }
        }
    }
}

Response parameters:

PayloadObject Object：

Attribute	Type	Optional	Description
state	Object	N	Device status object. For state examples of different capabilities, please see [Supported Device Capabilities].

Example of Response :

{
    “event”: {
        “header”: {
            “name”: “Response”,
            “message_id”: “Unique identifier, preferably a version 4 UUID”,
            “version”: “1”
        },
        “payload”: {
            “state”: {
                “power-consumption”: {
                    “type”: “summarize”, // Statistics type, String type, required. Optional parameters, “rlSummarize” (real-time statistical summary), “summarize” (current summary).
                    “electricityIntervals”: [ // Divide into multiple statistical records according to configuration.resolution
                        {
                            “usage”: 26.5, //The field power-consumption indicates, required. Number type, unit Celsius.
                            “start”: “2020-07-05T08:00:00Z”, //Start time, date type, required.
                            “end”: “2020-07-05T09:00:00Z” //End time, date type, required. If the interval between end and start is less than resolution, all reported records are considered invalid.
                        },
                        {
                            “usage”: 26.5, //The field power-consumption indicates, required. Number type, unit Celsius.
                            “start”: “2020-07-05T09:00:00Z”, //Start time, date type, required.
                            “end”: “2020-07-05T10:00:00Z” //End time, date type, required. If the interval between end and start is less than resolution, all reported records are considered invalid.
                        }
                    ]
                }
            }
        }
    }
}

Get Debug Logs Interface

Allow authorized users to obtain device debugging logs through this interface. NSPanel Pro Version ≥ 1.5.0

Failed to sync new device list, no log will be logged. If the synchronization is successful, a log (event_log) record will be generated for each serial_number
Gateway log storage limit is as follows.

event_log: Third-party report request log. A single device only saves the latest 3000 logs.
directive_log: Gateway sends request logs. A single device only saves the latest 3000 logs.

You can download the interface access logs within the selected time range through this interface. The file name is {start timestamp}{end timestamp}{device serial number}.json

The content format is:

[
  {
    "message_id": "message_id", //Message ID
    "ip": "", // Remote IP. Required.
    "req": { // Request record.
        "method": "GET", //  Request method. Required.
        "url": "", // Request url. Required.
        "body": "", // Request body, json string.Required. An empty string is allowed.
        "header": "" ， // Request header, json string. Required.
    },
    "res": { // Response record.
            "status_code": 200， // Status code. Required.
        "body": "" , // Response body, json string.Required. An empty string is allowed.
        "header": "" ， // Response header, json string. Required.}
       }
    }
]

URL：/open-api/v1/rest/thirdparty/debug-log/{serial_number}
Method：GET
Header：
- Content-Type: application/json
- Autorization: Bearer <token>

Response parameters:

Attribute	Type	Optional	Description
type	string	N	Log type:event_log: Third-party report request logdirective_log: The directive log sent by the gateway
from_index	int	Y	Start sequence number. Default is 0. An integer in the range [0,3000].
start_time	date	Y	Start timestamp, query specific time. If empty, default is 1 minute ago.
end_time	date	Y	End timestamp, query specific time. If iempty, default is current time.
limit	int	Y	The limit messages to be pulled, the range is an integer of [1,50]. If empty, default is 50.
order	string	Y	Sort by time range,DESC: Descending orderASC: Ascending orderDefault is DESC

Successful Response

Status Code: 200 OK

Response header：

Content-Type: application/octet-stream
Content-Disposition: attachment; filename={Start timestamp}{End timestamp}{device serial number}.json

Abnormal response

Status Code:

400 Parameter error
500 Gateway service exception

5. Server-sent events

MDN EventSource interface description：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

5.1 Instruction

The gateway supports pushing messages to the client using SSE (Server-sent events). The client can monitor SSE messages after obtaining the access credentials and can parse the content of the push messages according to the development interface event notification protocol after receiving the messages pushed by the gateway. It should be noted that the gateway currently uses the HTTP1.1 protocol, so SSE on the browser side there will be a maximum of no more than 6 connections limit (Specific instructions can be found in the MDN EventSource interface description.)

5.2 Common Format

URL：/open-api/v1/sse/bridge
Method：GET

Request parameters:

Name	Type	Optional	Description
access_token	string	N	Access Token

Note:

When requesting an SSE connection, the gateway will check the access_token, and it will return an authentication failure error if it is invalid. { “error”: 401, “data”: {}, “message”: “invalid access_token”}

<Module Name>#<Version>#<Message Type>

For example:

Module Name: device

Version: v1,v2,v3

Message Type: addDevice

Example:

const evtSource = new EventSource("http://<domain name or ip address>/open-api/v1/sse/bridge?access_token=xxxxxx");
evtSource.addEventListener('device#v1#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}

5.3 Device Module

a. Add Device Event

NSPanel Pro Version ≥ 1.7.0

Module Name：device

Version：v1

Message Type：addDevice

event.data parameters：

Name	Type	Optional	Description
payload	ResponseDeviceObjectObject – Interface the same with the Get Device List	N	device information

Example:

// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "My device",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "readWrite"
      },
      {
        "capability": "rssi",
        "permission": "read"
      }
    ],
    "protocol": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

b. Update Device State Event

NSPanel Pro Version ≥ 1.7.0

Module Name：device

Version：v1

Message Type：updateDeviceState

event.data parameters：

Name	Type	Optional	Description
endpoint	EndpointObject	N	Device Information
payload	object。 Structure the same as the device state	N	Device Status Data

EndpointObject Object:

Parameter	Type	Optional	Description
serial_number	string	N	Device unique Serial Number
third_serial_number	string	Y	The unique serial number of the third-party device. For devices connected through open interfaces, this field is required.

Example

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}

c. Update Device Info Event

NSPanel Pro Version ≥ 1.7.0

Module Name：device

Version：v1

Message Type：updateDeviceInfo

event.data parameters：

Name	Type	Optional	Description
endpoint	EndpointObject	N	Device Information
payload	DeviceChangeObject	N	Device Change Data

EndpointObject Object:

Attribute	Type	Optional	Description
serial_number	string	N	Device unique Serial Number
third_serial_number	string	Y	The unique serial number of the third-party device. For devices connected through open interfaces, this field is required.

DeviceChangeObject Object

Name	Type	Optional	Description
name	string	N	Device Name

Example

// event.data
{
"endpoint": {
"serial_number": "serial_number",
"third_serial_number": "third_serial_number"
},
"payload": {
"name": "device name"
}
}

d. Delete Device Event

NSPanel Pro Version ≥ 1.7.0

Module Name：device

Version：v1

Message Type：deleteDevice

event.data parameters：

Name	Type	Optional	Description
endpoint	EndpointObject	N	Device Information

EndpointObject Object:

Attribute	Type	Optional	Description
serial_number	string	N	Device unique Serial Number
third_serial_number	string	Y	The unique serial number of the third-party device. For devices connected through open interfaces, this field is required.

Example

// event.data
{
"endpoint": {
"serial_number": "serial_number",
"third_serial_number": "third_serial_number"
}
}

e. Update Device Online Event

NSPanel Pro Version ≥ 1.7.0

Module Name：device

Version：v1

Message Type：updateDeviceOnline

event.data parameters：

Name	Type	Optional	Description
endpoint	EndpointObject	N	Device Information
payload	DeviceChangeObject	N	Device Change Data

EndpointObject Object:

Attribute	Type	Optional	Description
serial_number	string	N	Device unique Serial Number
third_serial_number	string	Y	The unique serial number of the third-party device. For devices connected through open interfaces, this field is required.

DeviceChangeObject Object

Name	Type	Optional	Description
online	boolean	N	Device Online Status

Example

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}

Protokół API dla programistów