Wialon for developers User guide API reference unit update_command_definition

update_command_definition

To create, edit, or delete a command, use the unit/update_command_definition method.

Endpoint

Copied!

svc=unit/update_command_definition&params={
  "itemId": <long>,
  "id": <long>,
  "callMode": "<text>",
  "n": "<text>",
  "c": "<text>",
  "l": "<text>",
  "p": "<text>",
  "a": <long>,
  "f": <uint>,
  "jp": "<text>"
}

Parameters

The request must contain the following parameters:

Parameter	Description
`itemId`	Unit ID.
`id`	Command ID. When creating a command, specify 0. The system ignores this value and assigns the ID itself.
`callMode`	Action: `create`, `update`, or `delete`.

To create or edit a command, also specify the following parameters:

Parameter	Description
`n`	Command name.
`c`	Command type (see Command types).
`l`	Link type (see Link types).
`p`	Parameters.
`a`	Access rights that the user must have to execute this command (see check_items_billing).

The following parameters are optional:

Parameter	Description
`f`	Command flags. The default value is 0. The 0x4 flag means that a file is attached to the command. It’s set automatically if you upload a file with the request.
`jp`	JSON parameters of the command as text. If you don’t specify this parameter when updating a command, its JSON parameters are cleared.

Command types

Value	Command type
`block_engine`	Block the engine
`unblock_engine`	Unblock the engine
`custom_msg`	Send a custom message
`driver_msg`	Send a message to the driver
`download_msgs`	Download messages
`query_pos`	Request coordinates
`query_photo`	Request a photo
`query_photo_cam`	Request a photo from a specific camera
`query_ddd`	Request a DDD file from the tachograph
`output_on`	Activate an output
`output_off`	Deactivate an output
`send_position`	Send coordinates
`send_route`	Send a route
`send_waypoints`	Send waypoints
`set_report_interval`	Set a data transfer interval
`request_configuration`	Request the configuration
`upload_cfg`	Upload the configuration
`upload_sw`	Upload the firmware
`wiatag_service`	Start or stop WiaTag (for the WiaTag device type)
`secoon`	Activate the SECO (secure engine cut-off) function
`secooff`	Deactivate the SECO (secure engine cut-off) function

The list isn’t complete: device types can define other command types.

In Wialon Local, the secoon and secooff command types are available starting from version 2504.

Link types

Value	Link type
Empty string	Auto
`tcp`	TCP
`udp`	UDP
`vrt`	Virtual
`gsm`	SMS

Copying the attached file

To copy the file attached to a command of another unit, specify the 0x4 flag in f and the following parameters in addition to the ones required for creating or editing a command:

Parameter	Description
`oldItemId`	ID of the unit from which you want to copy the file.
`oldCmdId`	ID of the command whose file you want to copy.

Only the file is copied. The other command properties are taken from the request. If p is empty, the parameters of the source command are used. To copy the file, the user must have the View commands access right to the source unit.

Response

If a command is created or edited successfully, the response is returned in the following format:

Copied!

[
  <long>,          /* Command ID */
  {
    "id": <long>,  /* Command ID */
    "n": "<text>", /* Command name */
    "c": "<text>", /* Command type */
    "l": "<text>", /* Link type */
    "p": "<text>", /* Parameters */
    "a": <long>,   /* Access rights required to execute the command */
    "f": <uint>,   /* Flags */
    "jp": "<text>",/* JSON parameters; only if they're specified */
    "ct": <uint>,  /* Creation time (Unix timestamp) */
    "mt": <uint>   /* Last modification time (Unix timestamp) */
  }
]

In Wialon Local, the ct and mt fields are available starting from version 2304.

If a command is deleted successfully, the response is returned in the following format:

Copied!

[
  <long>,          /* Command ID */
  null
]

If the request fails, an error code is returned.

Error codes

Error code	Description
4	Wrong input parameters: a required parameter is missing or has a wrong type, `callMode` has an unsupported value, the command couldn’t be created or updated, or the source unit, command, or file for copying isn’t available.
6	The command with the specified `id` doesn’t exist (update and delete), or the command couldn’t be deleted.
7	The unit doesn’t exist, or the user doesn’t have the View commands and Create, edit, and delete commands access rights to it.

If you find a mistake in the text, please select it and press Ctrl+Enter.