NSPanel Pro Open API

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"
          }
        ],
        "protocal": "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

TypeDescription
stringString data type. UTF8 encoded.
numberNumber data type. double-precision 64-bit binary format IEEE 754
intIntegral data type.
objectObject data type. JSON-compliant object
string[]Array of string
int[]Array of integral
object[]Array of object
boolBoolean
dateTime 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 error is equal to 0, the content is successWhen 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 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: 

AttributeTypeOptionalDescription
app_namestringYApplication name description.

Successful data response:

Attribute

Type

Optional

Description

token

string

N

The interface access token. It’s valid for a long time, please save it

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
    • Autorization: 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"
}

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
  • MethodPUT
  • Header
    • Content-Type: application/json
    • Autorization: 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:空 Object {}

 

 

 

:::tips

 

 

 

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
    • Autorization: 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 {}

 

 

 

:::tips

 

 

 

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
    • Autorization: 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
    • Autorization: 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

:::tips

 

 

 

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
    • Autorization: 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:空 Object {}

 

 

 

:::tips

 

 

 

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 TypeValueNSPanel Pro Version
Plugplug≥ 1.5.0
Switchswitch≥ 1.5.0
Lightlight≥ 1.5.0
Curtaincurtain≥ 1.5.0
Door/Window SensorcontactSensor≥ 1.5.0
Motion sensormotionSensor≥ 1.5.0
Temperature sensortemperatureSensor≥ 1.5.0
Humidity sensorhumiditySensor≥ 1.5.0
Temperature and humidity sensortemperatureAndHumiditySensor≥ 1.5.0
Water leak detectorwaterLeakDetector≥ 1.5.0
Smoke detectorsmokeDetector≥ 1.5.0
Wireless buttonbutton≥ 1.5.0
Cameracamera≥ 1.5.0
General sensorsensor≥ 1.5.0

b. Supported Device Capabilities

NameDescriptionCapability&Permission ExampleAttribute(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 }}

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 CodeDescriptionNSPanel Pro Version
110000The sub-device/group corresponding to the id does not exist≥ 1.5.0
110001The gateway is in the state of discovering zigbee devices≥ 1.5.0
110006Failed 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
    • Autorization: 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
    • Autorization: Bearer <token>

Request parameters:

Attribute

Type

Optional

Description

name

string

N

Sub-device name

display_category

string

N

Device Type. Only support camera。

capabilities

CapabilityObject[]

N

Capability list. When display_category = camera, capabilities only include camera-stream capabilities.

protocal

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 support 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, 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
    • Autorization: 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",
        "name": "My Device",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocal": "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
    • Autorization: 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.

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
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
    • Autorization: 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"
}

4. Third-party Device Access

4.1 Access Instruction

Device Access

Third-party gateway Access

Access steps

  1. Determine the classification of the device in the gateway. The detail please check the [Supported Device Type].
  2. Determine the capabilities that the device can access. The detail please check the [Supported Device Capabilities].
  3. 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.
  4. 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.
  5. 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
    • Autorization: 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": "http://192.168.31.14/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 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 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": {}
}

Gateway sends the instruction interface through the device service address

  • Note:
  1. The three parties need to respond to the gateway’s request within 3s. Otherwise, the gateway will judge the command processing timeout.
  2. 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
{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "payload": {}
  }
}
Failure response
{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}
UpdateDeviceStates

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

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.
  1. event_log: Third-party report request log. A single device only saves the latest 3000 logs.
  2. 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.5.0

Module Name:device

Version:v1

Message Type:addDevice

event.data parameters:

 Name Type Optional Description
payloadResponseDeviceObjectObject – Interface the same with the Get Device ListNdevice 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"
      }
    ],
    "protocal": "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
  }
}

Pin It on Pinterest