Run advanced LWM2M shell commands

Write binary data, send raw CoAP requests, change the serialization format, start a firmware update, or restart an LWM2M device with shell commands.

The commands in this skill write raw bytes, bypass the LWM2M encoding, or change the whole device. Like all LWM2M shell commands, each command is the text of a c8y_Command operation, see Read and write LWM2M resources with shell commands. All commands in this skill work with LWM2M 1.0 and 1.1.

Before you send a command, check that the device accepts shell commands, see To check that the device accepts shell commands. Write the command text as described in Rules for the command text.

The examples use <device_id> for the ID of the LWM2M device, <operation_id> for the ID of an operation, and <path> for an LWM2M path. For a firmware update, they use <firmware_name>, <firmware_version>, and <firmware_url> for the name, the version, and the URL of the firmware.

Advanced commands

To write binary data to a resource

Give the binary data in one of the following forms:

• As hexadecimal characters, two for each byte. The number of characters must be even.
• As binary: followed by the ID of a file that is uploaded to Cumulocity. The agent reads the file and writes its content to the device.

The agent uses the content format in the binaryDeliveryEncoding fragment of the device, or OPAQUE if the device has no such fragment, see Advanced settings.

Send a Create an operation request with the writeb command:

POST /devicecontrol/operations
Content-Type: application/json
Accept: application/json

{
  "deviceId": "<device_id>",
  "description": "writeb /3442/0/150 010A0B020F",
  "c8y_Command": {
    "text": "writeb /3442/0/150 010A0B020F"
  }
}

The platform returns HTTP 201 and the operation with its id and "status": "PENDING". Note the id as <operation_id> and read the result, see To read the result of a command.

To send a raw CoAP request

A raw CoAP request bypasses the LWM2M layer. The agent does not check the request against the object model, and Cumulocity does not process the response further. Use raw CoAP requests only in exceptional cases.

Describe the request as JSON without spaces, with the following properties:

• method: Mandatory. One of get, post, put, delete, fetch, patch, or ipatch.
• uri: Optional. The LWM2M path, for example /3/0/0.
• contentFormat and accept: Optional. IANA content types, for example application/vnd.oma.lwm2m+json.
• payloadHex: Optional. The payload as hexadecimal characters.

Send a Create an operation request with the coap command. In the JSON body of the operation, escape the double quotes of the CoAP request:

POST /devicecontrol/operations
Content-Type: application/json
Accept: application/json

{
  "deviceId": "<device_id>",
  "description": "coap get /3/0/0",
  "c8y_Command": {
    "text": "coap {\"method\":\"get\",\"uri\":\"/3/0/0\"}"
  }
}

The platform returns HTTP 201. When the command is SUCCESSFUL, c8y_Command.result contains the CoAP response with responseCode, payloadHex, payloadString, and success.

To change the serialization format

The serialization command sets the content format that the agent uses for all later requests to the device: TLV, CBOR, TEXT, OPAQUE, JSON, SENML_JSON, or SENML_CBOR. DEFAULT restores the standard behavior. The agent stores the format in the LWM2M configuration of the device and sends no request to the device. See also Manage the LWM2M configuration of a device.

Send a Create an operation request with the serialization command:

POST /devicecontrol/operations
Content-Type: application/json
Accept: application/json

{
  "deviceId": "<device_id>",
  "description": "serialization SENML_JSON",
  "c8y_Command": {
    "text": "serialization SENML_JSON"
  }
}

The platform returns HTTP 201. When the command is SUCCESSFUL, its result is Serialization set.

To start a firmware update

The fwupdate command takes the name, the version, and the URL of the firmware, separated by semicolons and not by spaces. The command does not send a request to the device. It creates a separate c8y_Firmware operation, which performs the update.

Send a Create an operation request with the fwupdate command:

POST /devicecontrol/operations
Content-Type: application/json
Accept: application/json

{
  "deviceId": "<device_id>",
  "description": "fwupdate <firmware_name>;<firmware_version>;<firmware_url>",
  "c8y_Command": {
    "text": "fwupdate <firmware_name>;<firmware_version>;<firmware_url>"
  }
}

The platform returns HTTP 201. When the command is SUCCESSFUL, its result is Firmware update operation started. This only means that the update started.

To find the c8y_Firmware operation, send a Retrieve a list of operations request with the creationTime of your command as <creation_time>:

GET /devicecontrol/operations?deviceId=<device_id>&fragmentType=c8y_Firmware&dateFrom=<creation_time>

Follow the c8y_Firmware operation as described in Update the firmware of an LWM2M device.

To restart the device

The restart command takes no arguments. The agent executes the resource /3/0/4 on the device.

Send a Create an operation request with the restart command:

POST /devicecontrol/operations
Content-Type: application/json
Accept: application/json

{
  "deviceId": "<device_id>",
  "description": "restart",
  "c8y_Command": {
    "text": "restart"
  }
}

The platform returns HTTP 201. When the command is SUCCESSFUL, its result is CHANGED(204). The agent replaces the text of the command with Restart Device, so the original text is no longer in the operation.

To read the result of a command

Send a Retrieve a specific operation request:

GET /devicecontrol/operations/<operation_id>

Repeat the request until the status is SUCCESSFUL or FAILED, as described in Send an operation to a device. If the status is SUCCESSFUL, c8y_Command.result contains the result that the table in Advanced commands shows.

If the status is FAILED, the failureReason property describes the cause. In addition to the reasons in To read the result, the following reasons apply to the advanced commands:

• Contains Cannot parse CoAP request representation: The CoAP request is not valid JSON.
• Contains method: must not be blank: The CoAP request has no method.
• Contains Reading binary data failed: The hexadecimal value is malformed. Use an even number of hexadecimal characters.
• Contains No content provided to write to the device: The writeb command has no data.
• Contains Failed to read binary data for id: No file with this ID exists.
• Contains Unsupported serialization format: The format is not one of the formats listed in To change the serialization format.
• Contains Missing required parameter: firmware URL: The fwupdate command has fewer than three parts separated by semicolons.

If the status changes from EXECUTING back to PENDING, the device is not connected. The agent sends the command again when the device registers again. Do not create the command again.