On this page

Show all

Help Center/ ROMA Connect/ API Reference/ Device Integration APIs/ Device Management/ Creating a Device

Creating a Device

Updated on 2023-06-29 GMT+08:00

View PDF

Function

Creating a Device

URI

POST /v2/{project_id}/link/instances/{instance_id}/devices

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Appendix > Obtaining a Project ID in the ROMA Connect API Reference. Minimum: 0 Maximum: 32
instance_id	Yes	String	Instance ID. Minimum: 0 Maximum: 36

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token, which can be obtained by calling the IAM API (value of X-Subject-Token in the response header). Minimum: 1 Maximum: 100000

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
parent_device_id	No	Integer	Parent device ID. If there is no parent device, this parameter is left empty and the value is automatically rounded down. Minimum: 1 Maximum: 99999999999999999
product	Yes	ProductReferer object	Product.
password	No	String	Device password. The password must contain 8 to 32 characters, including at least one digit, one uppercase letter, one lowercase letter, and one special character (~!@#$%^&*()-_=+\|[{}];:<>/?). Minimum: 8 Maximum: 32
user_name	No	String	Device user name, which is a string of 10 to 50 characters containing letters, hyphens (-), and digits. Minimum: 10 Maximum: 50
device_name	Yes	String	Device name. The value is a string of 2 to 64 characters, which can contain letters, digits, and the following special characters: ()_,#.?''-@%&!, Minimum: 2 Maximum: 64
node_id	Yes	String	Physical number of a device. The value is a string of 2 to 64 characters, which can contain only letters, digits, underscores (_), and hyphens (-). Generally, the MAC address or IMEI is used. Minimum: 2 Maximum: 64
app_id	Yes	String	Application ID. Minimum: 0 Maximum: 36
status	No	Integer	Device status. The options are as follows: 0 (enabled) and 1 (disabled). If this parameter is left empty, the default value 0 is used. Minimum: 0 Maximum: 10
description	No	String	Description. Minimum: 0 Maximum: 200
tags	No	Array of strings	Tag. Minimum: 1 Maximum: 64

**Table 4** ProductReferer
Parameter	Mandatory	Type	Description
product_id	No	Integer	Product ID. The product ID is mandatory if the manufacturer ID and model are not set. Minimum: 1 Maximum: 99999999999999999
product_name	No	String	Product name. Minimum: 0 Maximum: 64
manufacturer_id	No	String	Manufacturer ID. If the product ID is not specified, the manufacturer ID and model are mandatory. Minimum: 0 Maximum: 64
model	No	String	Model. If the product ID is not specified, the manufacturer ID and model are mandatory. Minimum: 0 Maximum: 64
protocol_type	No	Integer	Protocol type of the product. 0: mqtt 1: CoAP 2: modbus 4: opcua 5: extended protocol Minimum: 0 Maximum: 5
product_type	No	Integer	Product type. The options are as follows: 0: common; 1: gateway. Minimum: 0 Maximum: 10
extend_protocol_name	No	String	Extended protocol name. Minimum: 0 Maximum: 64

Response Parameters

Status code: 201

**Table 5** Response body parameters
Parameter	Type	Description
permissions	Array of strings	Permission.
id	Integer	Device ID. Minimum: 1 Maximum: 99999999999999999
device_id	Integer	Device ID (compatible with 20.0). Minimum: 1 Maximum: 99999999999999999
product	ProductReferer object	Product.
device_name	String	Device name. The value is a string of 2 to 64 characters, which can contain letters, digits, and the following special characters: ()_,#.?''-@%&!, Minimum: 2 Maximum: 64
instance_id	String	Instance ID. Minimum: 2 Maximum: 64
client_id	String	Client ID, which is the unique device ID generated by the ROMA platform. Minimum: 0 Maximum: 32
node_id	String	Physical number of a device. The value is a string of 2 to 64 characters, which can contain only letters, digits, underscores (_), and hyphens (-). Generally, the MAC address or IMEI is used. Minimum: 2 Maximum: 64
app_name	String	Application name. Minimum: 0 Maximum: 256
status	Integer	Device status. The options are as follows: 0: enabled; 1: disabled. Minimum: 0 Maximum: 10
online_status	Integer	Connection status. The options are as follows: 0: disconnected; 1: online; 2: offline. Minimum: 0 Maximum: 10
description	String	Description. Minimum: 0 Maximum: 200
authentication	Authentication object	Authentication.
created_user	CreatedUser object	Name of the user who created the attribute.
last_updated_user	LastUpdatedUser object	User who performed the last update.
tags	Array of strings	Tag. Minimum: 1 Maximum: 64
created_datetime	Long	Creation start time. The format is timestamp(ms) and the UTC time zone is used. Minimum: 1 Maximum: 99999999999999999
last_updated_datetime	Long	Last modification time (timestamp, in milliseconds). The UTC time zone is used. Minimum: 1 Maximum: 99999999999999999
connect_address	String	Device access address. Minimum: 0 Maximum: 200
ssl_connect_address	String	Device access SSL address. Minimum: 0 Maximum: 200
ipv6_connect_address	String	IPv6 address for device access. This parameter is valid only when IPv6 is enabled. Minimum: 0 Maximum: 200
ipv6_ssl_connect_address	String	IPv6 SSL address for device access. This parameter is valid only when IPv6 is enabled. Minimum: 0 Maximum: 200
node_type	Integer	Node type. The options are as follows: 0: direct connection; 1: gateway; 2: subdevice. Minimum: 1 Maximum: 99999999999999999
device_type	Integer	Device type. The options are as follows: [/topic/body/section/table/tgroup/tbody/row/entry/p/br {""}) (br]0: common device (without a child device or parent device); [/topic/body/section/table/tgroup/tbody/row/entry/p/br {""}) (br]1: gateway device (which can contain subdevices); [/topic/body/section/table/tgroup/tbody/row/entry/p/br {""}) (br]2: child device (belonging to a gateway device). Minimum: 0 Maximum: 10
app_id	String	Application ID. Minimum: 0 Maximum: 36

**Table 6** ProductReferer
Parameter	Type	Description
product_id	Integer	Product ID. The product ID is mandatory if the manufacturer ID and model are not set. Minimum: 1 Maximum: 99999999999999999
product_name	String	Product name. Minimum: 0 Maximum: 64
manufacturer_id	String	Manufacturer ID. If the product ID is not specified, the manufacturer ID and model are mandatory. Minimum: 0 Maximum: 64
model	String	Model. If the product ID is not specified, the manufacturer ID and model are mandatory. Minimum: 0 Maximum: 64
protocol_type	Integer	Protocol type of the product. 0: mqtt 1: CoAP 2: modbus 4: opcua 5: extended protocol Minimum: 0 Maximum: 5
product_type	Integer	Product type. The options are as follows: 0: common; 1: gateway. Minimum: 0 Maximum: 10
extend_protocol_name	String	Extended protocol name. Minimum: 0 Maximum: 64

**Table 7** Authentication
Parameter	Type	Description
user_name	String	One-model-one-secret or one-device-one-secret username. Minimum: 0 Maximum: 64
password	String	One-model-one-secret or one-device-one-secret password. The password must contain 8 to 32 characters, including at least one digit, one uppercase letter, one lowercase letter, and one special character (~!@#$%^&*()-_=+\|[{}];:<>/?). Minimum: 0 Maximum: 64

**Table 8** CreatedUser
Parameter	Type	Description
user_id	String	User ID (reserved). Minimum: 0 Maximum: 64
user_name	String	Username. Minimum: 0 Maximum: 64

**Table 9** LastUpdatedUser
Parameter	Type	Description
user_id	String	User ID (reserved). Minimum: 0 Maximum: 64
user_name	String	Username. Minimum: 0 Maximum: 64

Status code: 400

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx. Minimum: 0 Maximum: 64
error_msg	String	Error description. Minimum: 0 Maximum: 200
request_id	String	Message ID. Minimum: 0 Maximum: 64

Status code: 404

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx. Minimum: 0 Maximum: 64
error_msg	String	Error description. Minimum: 0 Maximum: 200
request_id	String	Message ID. Minimum: 0 Maximum: 64

Status code: 500

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx. Minimum: 0 Maximum: 64
error_msg	String	Error description. Minimum: 0 Maximum: 200
request_id	String	Message ID. Minimum: 0 Maximum: 64

Example Requests

{
  "parent_device_id" : 10001,
  "product" : {
    "product_id" : 10001,
    "product_name" : "testproduct",
    "manufacturer_id" : "test",
    "model" : "mate30pro",
    "protocol_type" : 0,
    "product_type" : 0
  },
  "password" : "Testpassword@1",
  "device_name" : "device",
  "node_id" : "D32145A100FF",
  "app_id" : "ef3845be-091a-4ab5-869a-9de0025e2165",
  "status" : 0,
  "description" : "device",
  "tags" : [ "tag1", "tag2" ]
}

Example Responses

Status code: 201

Created

{
  "permissions" : [ "read", "access", "delete", "modify" ],
  "id" : 711537,
  "device_id" : 711537,
  "parent_device_id" : 711536,
  "parent_device_name" : "parent-device",
  "product" : {
    "product_id" : 116303,
    "product_name" : "p1",
    "manufacturer_id" : "p1",
    "model" : "p1",
    "product_type" : 0,
    "protocol_type" : 0
  },
  "device_name" : "device",
  "instance_id" : "8993a690-cf61-46af-880d-587d823d14e5",
  "client_id" : "D116303711537sGDtK",
  "node_id" : "string",
  "app_name" : "app",
  "status" : 0,
  "online_status" : 2,
  "description" : "device",
  "authentication" : {
    "user_name" : "F01A8D25FE6E4CF5A286B711B31888AE",
    "password" : "************************"
  },
  "created_user" : {
    "user_id" : "",
    "user_name" : "user"
  },
  "last_updated_user" : {
    "user_id" : "",
    "user_name" : "user"
  },
  "tags" : [ ],
  "created_datetime" : 1607408244841,
  "last_updated_datetime" : 1607422571094,
  "connect_address" : "xx.xx.xx.xx",
  "ssl_connect_address" : "xx.xx.xx.xx",
  "ipv6_connect_address" : "xx.xx.xx.xx",
  "ipv6_ssl_connect_address" : "xx.xx.xx.xx",
  "node_type" : 0,
  "device_type" : 0,
  "app_id" : "cb4b3ec0-8f7f-432f-b05e-fc149d05da5d"
}

Status code: 400

Bad Request

{
  "error_code" : "SCB.00000000",
  "error_msg" : "Parameter is not valid for operation [romalink.link-device.save]. Parameter is [parent_device_id]. Processor is [body].",
  "request_id" : "cb39e78a-afd3-4e04-901d-70468b1c23dc-1619602712496-cnnorth7a-P-romalink-service01"
}

Status code: 404

Not Found

{
  "error_code" : "ROMA.00110006",
  "error_msg" : "The resource does not exist. Check whether the resource ID ff38023c-0854-4779-847d-72528e1f5da1 is correct.",
  "request_id" : "624c8be1-39b6-47b7-941d-c159aced368a-1619602544650-cnnorth7a-P-romalink-service01"
}

Status code: 500

Internal Server Error

{
  "error_code" : "ROMA.00110002",
  "error_msg" : "The instance does not exist. project_id: 397cd10b30544c588b2f4a56d83856c4, instance_id: f3bb386a-23ec-47aa-9943-4c60ac658611",
  "request_id" : "c8c06d0a-be92-4fdf-9d10-bc20131ab158-1619593104919-cnnorth7a-P-romalink-service01"
}

Status Codes

Status Code	Description
201	Created
400	Bad Request
404	Not Found
500	Internal Server Error

Error Codes

See Error Codes.

Parent topic: Device Management

Previous topic: Device Management

Next topic: Querying Devices

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot