1. Tutorials
  2. Commands API

Commands Api

What are Commands?

Commands are used to communicate with one or more specific devices. Commands will be delivered directly to target devices that are connected via MQTT, or devices may check periodically for outstanding commands via HTTP.


The Commands API allows you to send custom user-defined commands to devices and allows devices to issue their responses. The Commands API can also be used to view and audit the history of recently sent commands, along with the device responses.

Sending Commands

You can send a command to one or more devices using the Send Command HTTP endpoint. This will POST the command to M2X which subsequently delivers the command to all target devices via MQTT, provided that the devices is connected and subscribed to the Commands MQTT topic thread.


Example "Send Command" JSON request:

{ "name": "CHECK_UPDATES",
  "data": { "updates_server": "https://updates.example.com/" },
  "targets": { "devices": ["3d15f9f98ba9a4beb4790ebad4311cd6",
                           "65b89448f954f49e42b746d73b385cbb",
                           "9033bda03e2cad5cb757d024aa4a8462"] } }

All commands that are posted to a device can be viewed via that Device's List of Received Commands endpoint. Or you can view an account level list of commands via the List Sent Commands endpoint.

Receiving Commands

M2X delivers commands in near real-time via MQTT by publishing the command data to the m2x/<Device Primary API Key>/commands topic thread. Connected devices that are subscribed to this thread will receive the commands as they arrive.


One caveat, if the device is not connected when the command is delivered via MQTT it will need to check for any pending commands once it reconnects (if missing a command is not desired).

Processing Commands

After a device receives a command, and optionally acts on the command, it can deliver a status update to M2X to indicate that the command was received and processed. There are two HTTP endpoints which allow the device to either mark the command as Processed, indicating that the command was accepted, or Reject the command.

Examples

Here are some code samples for receiving and processing commands: