NSPanel Pro Open API

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.

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

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

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

Type of Data

Generic Response Results

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

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

Resource List

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: None

Successful data response:

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

Status Code: 200 OK

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

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

Status Code:  200 OK

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

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

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

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

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

Status Code: 200 OK

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

a. Set the Screen Brightness

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

Request Parameters: 

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

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

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

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

Status Code: 200 OK

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

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

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

Status Code: 200 OK

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

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

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

Status Code: 200 OK

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

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

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

Status Code: 200 OK

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

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',
    },
}

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

d. Special Error Code and Description

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

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

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

Status Code: 200 OK

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

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

Status Code: 200 OK

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

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

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

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

Status Code: 200 OK

{
  "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
  • Autorization: Bearer <token>

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

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

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

Status Code: 200 OK

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

// 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”
}

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

// 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
    }
}

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:

EventObject Object

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

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

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

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

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

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

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.

Request parameters:

DirectiveObject Object

HeaderObject Object

EndpointObject Object

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

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

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

  "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)
            ]
          }
        }
      ]
    }
  }
}

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

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);
  }
}

// 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
  }
}

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

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

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

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