Registering a Device (Verification Code Mode)
Typical Scenario
Before a device accesses the platform by using verification code, an application needs to call this API to register the device with the platform and set a unique identification code of the device (such as the IMEI) as the verification code. Then, the device can use the unique identification code to get authenticated and connect to the platform.
API Function
This API is used by an application to register a device with the platform. After registration, the device can connect to the platform.
API Description
1 | RegDirectDeviceOutDTO regDirectDevice(RegDirectDeviceInDTO2 rddInDto, String appId, String accessToken) throws NorthApiException
|
Class
DeviceManagement
Parameter Description
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| appId | Mandatory | String | query | If the device belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application. |
| accessToken | Mandatory | String | header | If the Periodically Refreshing a Token API is called, set this parameter to null. Otherwise, set this parameter to the accessToken obtained by the Authentication API. |
| rddInDto | Mandatory | RegDirectDeviceInDTO2 | body | For details, see RegDirectDeviceInDTO2 structure. |
RegDirectDeviceInDTO2 structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| deviceInfo | Optional | DeviceInfoDTO | Body | Indicates information about the device. For details, see DeviceInfo structure. |
| imsi | Optional | String(1-64) | Body | Indicates the IMSI of an NB-IoT device. |
| isSecure | Optional | Boolean | Body | Indicates whether the device is secure. The default value is false.
NOTE: If a user needs to register a secure device, this parameter must be specified as true. |
| verifyCode | Optional | String(256) | body | Specifies a unique device verification code. It is recommended that you keep the value of this parameter the same as that of nodeId. If this parameter is specified in the request, it is returned in the response. If this parameter is not specified in the request, it is automatically generated by the platform. In the NB-IoT solution, this parameter is mandatory and must be set to the same value as nodeId. |
| nodeId | Mandatory | String(256) | body | Uniquely identifies a device. The value of this parameter must be the same as the device ID reported by the device. Generally, the MAC address, serial number, or IMEI is used as the node ID. NOTE: When the IMEI is used as the node ID, the node ID varies depending on the chip provided by the manufacturer.
|
| endUserId | Optional | String(256) | body | Identifies an end user. In the NB-IoT solution, this parameter is set to the IMSI of the device. In the SmartHome solution, this parameter is set to the application account. |
| psk | Optional | String(8-32) | body | If the pre-shared key (PSK) is specified in the request, the platform uses the specified PSK. If the PSK is not specified in the request, the PSK is generated by the platform. The value is a string of characters, including uppercase letters A to F, lowercase letters a to f, and numbers 0 to 9. |
| timeout | Optional | Integer(>=0) | Body | Indicates the validity period for device registration. When this API is called to register a device, the device can be bound within the validity period. If the device is not bound within the validity period, the registration information will be deleted. The value ranges from 0 to 2147483647. If this parameter is set to 0, the device verification code is always valid. (The recommended value is 0.) The default value is 0. The default value can be configured. For details, contact the platform maintenance personnel. Unit: second |
| productId | Optional | String(256) | Body | Identifies the product to which the device belongs. |
DeviceInfoDTO structure
| Parameter | Mandatory or Optional | Type | Location | Description |
|---|---|---|---|---|
| manufacturerId | Optional | String(256) | Body | Uniquely identifies a manufacturer. |
| manufacturerName | Optional | String(256) | Body | Indicates the manufacturer name. |
| deviceType | Optional | String(256) | Body | Indicates the device type. The upper camel case is used, for example, MultiSensor, ContactSensor, and CameraGateway. |
| model | Mandatory | String(256) | Body | Indicates the device model. In Z-Wave, the format is productType + productId. The value is a hexadecimal value in the format of XXXX-XXXX. Zeros are added if required, for example, 001A-0A12. The format in other protocols is still to be determined. |
| protocolType | Optional | String(256) | Body | Indicates the protocol used by the device. The value options are CoAP, huaweiM2M, Z-Wave, ONVIF, WPS, Hue, WiFi, J808, Gateway, ZigBee, and LWM2M. |
Return Value
RegDirectDeviceOutDTO
| Parameter | Type | Description |
|---|---|---|
| deviceId | String(256) | Identifies a device. |
| verifyCode | String(256) | Indicates the device verification code, with which the device can get authenticated and connect to the platform. If this parameter is specified in the request, it is returned in the response. If this parameter is not specified in the request, it is automatically generated by the platform. |
| timeout | Integer | Indicates the validity period of the verification code, in seconds. The device must connect to the platform within this period. (If this parameter is set to 0, the verification code does not expire.) |
| psk | String(32) | Indicates a random PSK. If the PSK is carried in the request, this PSK is used. Otherwise, the platform generates a random PSK. |
Error Codes
| HTTP Status Code | Error Code | Error Description | Remarks |
|---|---|---|---|
| 200 | 103028 | The license pool resources. | The license resources have been used up. |
| 400 | 100003 | Invalid verification code. | The verification code is invalid. Recommended handling: Check whether verifyCode carried in the API request is correct. If verifyCode is not carried in the API request, contact IoT platform maintenance personnel. |
| 400 | 100007 | Bad request message. | The request message contains invalid parameters. Recommended handling: The value of deviceId is not assigned. Set this parameter based on the description of request parameters. |
| 400 | 100416 | The device has already been bounded. | The device has been bound to the IoT platform. Recommended handling: Check whether the device is registered. |
| 400 | 100426 | The node ID is duplicated. | The value of nodeId is duplicated. Recommended handling: Check whether nodeId carried in the API request is correct. |
| 400 | 50400 | An input parameter is invalid. | An input parameter is invalid. Recommended handling: Check whether parameters carried in the API call request are valid. |
| 401 | 100025 | The application ID used for authentication does not exist. | The application ID used for authentication does not exist. Recommended handling:
|
| 403 | 100203 | The application does not exist. | The application does not exist. Recommended handling:
|
| 403 | 100217 | The application has not been authorized. | The application has not been authorized. Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null. |
| 403 | 1010009 | The application calls the API at a frequency that exceeds the flow control threshold. | The application calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default). Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency. |
| 403 | 1010005 | Invalid access token or application ID. | The access token is invalid. Recommended handling: Check whether accessToken carried in the API request is correct. |
| 403 | 600002 | The product does not exist. | The product does not exist. Recommended handling: Check whether productId is correct. |
| 500 | 100001 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
| 500 | 100203 | The application does not exist. | The authorized application does not exist. Recommended handling:
|
| 500 | 100412 | The number of devices has reached the upper limit. | The number of devices under the current application reaches the upper limit. Recommended handling: Check whether the number of devices under the current application reaches the upper limit. |
| 500 | 100441 | The number of non-security devices has reached the upper limit. | The number of non-security devices has reached the upper limit. Recommended handling:
|
| 500 | 103026 | The license does not exist. | The license does not exist. Recommended handling: An internal license error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
| 500 | 50252 | Internal server error. | An internal server error occurs. Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel. |
Last Article: Device Management
Next Article: Refreshing a Device Secret
Did this article solve your problem?
Thank you for your score！Your feedback would help us improve the website.