Request and Response Data

The gateway provides MQTT APIs for querying the device and gateway info or configure the Device settings. API requests and responses are exchanged in JSON format. Request messages are published to the configured Request Data topic, while response messages are returned through the configured Response Data topic.

Note: The Request data and Response data topics must be different.

Request Data

A request message is a JSON object containing the following fields:


Parameter	Type	Required	Description
id	string	Yes	Identifier of the request. This is a random value.
method	string	Yes	Operation method. Supported values depend on the API.
url	string	Yes	API resource path.
body	object	No	Request payload. Include it when the operation requires additional input data, typically for POST and PUT operations.

Request Example:

{
  "id": "1",
  "method": "POST",
  "url": "/ns/device/add",
  "body": {
    "name": "EM300",
    "description": "em300",
    "devEUI": "24E124136A456465",
    "classMode": "Class A",
    "netAccess": "OTAA",
    "appKey": "5572404c696e6b4c6f52613230313823",
    "fPort": 1,
    "skipFCntCheck": false
  }
}

Response Data

A response message is a JSON object returned by the gateway after processing a request. It contains the following fields:


Parameter	Type	Description
id	string	Identifier of the response. This value is the same as in the corresponding request.
method	string	Method of the corresponding request.
url	string	API resource path of the corresponding request.
body	object	Response payload. The structure depends on the request.

Response Example:

{
  "id": "1",
  "method": "POST",
  "url": "/ns/device/add",
  "body": {
    "code": 200,
    "error": ""
  }
}

Add Device

Adds a LoRaWAN^® end device to the gateway embedded network server.

Method: POST

URL: /ns/device/add

Request Data

The request message body contains the following fields:


Parameter	Type / Range	Required	Default	Description
name	string, max. 192 chars	Yes	devEUI	Device name. Allows Chinese characters, English letters, numbers, underscores, and hyphens. Must be unique in the device list.
description	string, max. 384 chars	Yes	-	Device description.
applicationIds	string array	No	-	ID of existing applications.
devEUI	string, 16 HEX chars	Yes	-	Unique Device EUI.
classMode	string	Yes	Class A	Device class. Supported values: `Class A`, `Class C`.
netAccess	string	Yes	-	Network activation mode. Supported values: `OTAA`, `ABP`.
appKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `OTAA`.
devAddr	string, 8 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
nwkSKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
appSKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
fCntUp	uint32	No	0	Initial uplink frame counter for ABP devices. Range: 0-4294967295.
fCntDown	uint32	No	0	Initial downlink frame counter for ABP devices. Range: 0-4294967295.
fPort	integer	Yes	1	Device application port. Range: 1-233.
skipFCntCheck	boolean	Yes	false	Specifies whether disable frame counter validation.
rxDROffset1	string	No	0	RX1 datarate offset. Range: 0-7.
rxDataRate2	integer	No	Depend on Channel Plan	RX2 datarate. See options on Reference Table.
rxFreq2	unsigned integer	No	Depend on Channel Plan	RX2 frequency. See options on Reference Table.
enableUplinkChannelStr	string	No	All	This parameter only works with CN470/US915/AU915 channel plans. Examples: 1,40: Enable Channel 1 and 40 1-40: Enable Channel 1-40 1-40, 60: Enable Channel 1-40 and 60 Null: Enable all channels
classCTimeout	integer	No	0	The time to wait for a downlink response from class C devices. Unit: s.

Request Example - OTAA

{
  "id": "1",
  "method": "POST",
  "url": "/ns/device/add",
  "body": {
    "name": "EM300",
    "description": "Warehouse temperature sensor",
    "applicationIds": ["1","2"],
    "devEUI": "24E124136A456465",
    "classMode": "Class A",
    "netAccess": "OTAA",
    "appKey": "5572404c696e6b4c6f52613230313823",
    "fPort": 85,
    "skipFCntCheck": false
  }
}

Request Example - ABP

{
  "id": "2",
  "method": "POST",
  "url": "/ns/device/add",
  "body": {
    "name": "EM300-ABP",
    "description": "Warehouse temperature sensor",
    "applicationIds": ["3"],
    "devEUI": "24E124136A456466",
    "classMode": "Class A",
    "netAccess": "ABP",
    "devAddr": "06B18CCF",
    "nwkSKey": "5572404c696e6b4c6f52613230313823",
    "appSKey": "5572404c696e6b4c6f52613230313823",
    "fCntUp": 0,
    "fCntDown": 0,
    "fPort": 85,
    "skipFCntCheck": false
  }
}

Response Data

The response message body contains the following fields:


Parameter	Type	Description
code	integer	Result code. `200` indicates success. See the Return Code List for failure codes.
error	string	Error message. Empty when the operation succeeds.

Response Example

{
  "id": "1",
  "method": "POST",
  "url": "/ns/device/add",
  "body": {
    "code": 200,
    "error": ""
  }
}

Delete Device

Deletes one or more LoRaWAN^® end devices from the gateway embedded network server.

Method: DELETE

URL: /ns/device

Request Data

The request message body contains the following fields:


Parameter	Type	Required	Default	Description
ids	array of strings	Yes	-	Device EUIs to delete.

Request Example

{
  "id": "1",
  "method": "DELETE",
  "url": "/ns/device",
  "body": {
    "ids": [
      "24E124136A456465",
      "24E124136A456069"
    ]
  }
}

Response Data

The response message body contains the following fields:


Parameter	Type	Description
code	integer	Result code. `200` indicates success. See the Return Code List for failure codes.
error	string	Error message. Empty when the operation succeeds.

Response Example

{
  "id": "1",
  "method": "DELETE",
  "url": "/ns/device",
  "body": {
    "code": 200,
    "error": ""
  }
}

Enquire Device

Queries devices added on the gateway embedded network server.

Method: GET

URL: /ns/device?search=&limit=10&offset=0&applicationId=0

Request Data

The request URL supports the following query parameters:


Parameter	Type	Required	Default	Description
search	string	No	-	The devEUI or device name to search. Leave it blank to enquire all devices.
limit	integer	No	20	Maximum number of devices to enquire. Range: 0-20 (UG63) or 0-100 (SG50).
offset	integer	No	0	Specifies the device from which the enquiry starts.
applicationId	integer	No	-	Enquires devices under the specified application. Leave it blank to enquire all devices.

Request Example - Enquire All Devices

{
  "id": "1",
  "method": "GET",
  "url": "/ns/device?search=&limit=100&offset=0"
}

Request Example - Enquire Devices Under One Application

{
  "id": "2",
  "method": "GET",
  "url": "/ns/device?search=&limit=10&offset=0&applicationId=1"
}

Request Example - Enquire One Device

{
  "id": "3",
  "method": "GET",
  "url": "/ns/device?search=24E124136A456465&limit=10&offset=0"
}

Response Data

The response message body contains the following fields:


Parameter	Type	Description
total	string	The device amount of enquiry.
result	array	The enquiry result.
result[].name	string	Device name.
result[].description	string	Device description.
result[].devEUI	string	Device EUI.
result[].appEUI	string	Device App EUI.
result[].classMode	string	Device class mode.
result[].netAccess	string	Device join type.
result[].fPort	integer	Device application port.
result[].skipFCntCheck	boolean	Whether disable frame count validation.
result[].devAddr	string	Device Address. Required when `netAccess` is `ABP`.
result[].appKey	string	Application Key. Required when `netAccess` is `OTAA`.
result[].nwkSKey	string	Network Session Key. Required when `netAccess` is `ABP`.
result[].appSKey	string	Application Session Key. Required when `netAccess` is `ABP`.
result[].fCntUp	integer	Uplink frame counter.
result[].fCntDown	integer	Downlink frame counter.
result[].active	integer	`1`: activate; `0`: de-activate.
result[].applicationId	string	Application ID.
result[].applicationName	string	Application name.
result[].createTime	string	The time to create the device.
result[].lastTime	string	The last update time.
deviceMax	integer	The maximum supported device number.

Response Example

{
  "id": "1",
  "method": "GET",
  "url": "/ns/device?search=&limit=100&offset=0",
  "body": {
    "total": 2,
    "result": [
      {
        "name": "EM300",
        "description": "em300",
        "devEUI": "24E124136A456465",
        "appEUI": "",
        "classMode": "Class A",
        "netAccess": "OTAA",
        "fPort": 1,
        "skipFCntCheck": false,
        "devAddr": "",
        "appKey": "5572404c696e6b4c6f52613230313823",
        "nwkSKey": "",
        "appSKey": "",
        "fCntUp": 0,
        "fCntDown": 0,
        "active": 0,
        "applicationId": "3",
        "applicationName": "test",
        "createTime": "2025-04-12 13:22:06+0800",
        "lastTime": "",
        "channelsConfiguredFlag": 0,
        "rx2ConfiguredFlag": 0,
        "newChannelsConfiguredFlag": 0
      },
      {
        "name": "AM300",
        "description": "",
        "devEUI": "24e124707E094237",
        "appEUI": "24e124c0002a0001",
        "classMode": "Class A",
        "netAccess": "OTAA",
        "fPort": 85,
        "skipFCntCheck": false,
        "devAddr": "06b18ccf",
        "appKey": "5572404c696e6b4c6f52613230313822",
        "nwkSKey": "cb6125fde2cc1894e5984db1016b1cda",
        "appSKey": "eda3215c1a9c34ca6bc8ec76373e9da4",
        "fCntUp": 32,
        "fCntDown": 32,
        "active": 1,
        "applicationId": "3",
        "applicationName": "test",
        "createTime": "2025-04-10 13:29:42+0800",
        "lastTime": "59 seconds ago",
        "channelsConfiguredFlag": 1,
        "rx2ConfiguredFlag": 0,
        "newChannelsConfiguredFlag": 0
      }
    ],
    "deviceMax": 20
  }
}

Modify Device

Modifies the settings of an existing device. Before modifying a device, it is suggested to enquire this device first.

Method: PUT

URL: /ns/device/{devEUI}

Request Data

The request message body contains the following fields:


Parameter	Type / Range	Required	Default	Description
name	string, max. 192 chars	Yes	devEUI	Device name. Allows Chinese characters, English letters, numbers, underscores, and hyphens. Must be unique in the device list.
description	string, max. 384 chars	Yes	-	Device description.
applicationIds	string array	No	-	ID of existing applications.
devEUI	string, 16 HEX chars	Yes	-	Unique Device EUI.
classMode	string	Yes	Class A	Device class. Supported values: `Class A`, `Class C`.
netAccess	string	Yes	-	Network activation mode. Supported values: `OTAA`, `ABP`.
appKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `OTAA`.
devAddr	string, 8 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
nwkSKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
appSKey	string, 32 HEX chars	Conditional	-	Required when `netAccess` is `ABP`.
fCntUp	uint32	No	0	Initial uplink frame counter for ABP devices. Range: 0-4294967295.
fCntDown	uint32	No	0	Initial downlink frame counter for ABP devices. Range: 0-4294967295.
fPort	integer	Yes	1	Device application port. Range: 1-233.
skipFCntCheck	boolean	Yes	false	Specifies whether disable frame counter validation.
rxDROffset1	string	No	0	RX1 datarate offset. Range: 0-7.
rxDataRate2	integer	No	Depend on Channel Plan	RX2 datarate. See options on Reference Table.
rxFreq2	unsigned integer	No	Depend on Channel Plan	RX2 frequency. See options on Reference Table.
enableUplinkChannelStr	string	No	All	This parameter only works with CN470/US915/AU915 channel plans. Examples: 1,40: Enable Channel 1 and 40 1-40: Enable Channel 1-40 1-40, 60: Enable Channel 1-40 and 60 Null: Enable all channels
classCTimeout	integer	No	0	The time to wait for a downlink response from class C devices. Unit: s.

Request Example

{{
    "id": "123",
    "method": "PUT",
    "url": "/ns/device/24E124FFFEF97276",
    "body": {
        "devEUI": "24E124FFFEF97276",
        "name": "Device Updated",
        "description": "Updated description",
        "classMode": "Class A",
        "netAccess": "OTAA",
        "fPort": 1,
        "skipFCntCheck": false,
        "appKey": "5572404c696e6b4c6f52613230313823"
    }
}

Response Data

The response message body contains the following fields:


Parameter	Type	Description
code	integer	Result code. `200` indicates success. See the Return Code List for failure codes.
error	string	Error message. Empty when the operation succeeds.

Response Example

{
  "id": "1",
  "method": "PUT",
  "url": "/ns/device/24E124FFFEF97276",
  "body": {
    "code": 200,
    "error": ""
  }
}

Enquire Gateway Info

Queries information about the gateway.

Method: GET

URL: /gatewayinfo

Request Data

This request does not contain a request body.

Request Example

{
  "id": "1",
  "method": "GET",
  "url": "/gatewayinfo"
}

Response Data

The response message body contains the gateway information fields described in the Gateway Info.

Response Example

{
  "id": "1",
  "method": "GET",
  "url": "/gatewayinfo",
  "body": {
    "tunnel_support": true,
    "device_info": {
      "model": "UG63-L08GL-868M",
      "region": "EU868",
      "eui": "24E124FFFEF9A1E2",
      "gateway_id": "24E124FFFEF9A1E2",
      "firmware_version": "64.0.0.3-r1",
      "hardware_version": "V1.1",
      "cpu_tempeture": "53.3°",
      "profile_version": "v1.1",
      "tsl_version": "v1.0"
    },
    "network_info": {
      "modem_version": "EG912UGLAAR03A09M08_01.200.01.200",
      "cellular_ip": "-",
      "imei": "869487060869384",
      "iccid": "-",
      "link": 1,
      "cellular_status": 0,
      "modem_status": 0,
      "wan_type": 1,
      "wan_status": 1,
      "wan_ip": "192.168.45.196",
      "wan_mac": "24:e1:24:f9:a1:e2"
    }
  }
}

Return Code List


Code	Description
200	Success
20101001	Parameter Error
20101002	devEUI exist
20101003	Device number max
20101004	URI is null