Menu

Device Control Overview

In this article:

    What is Device Control?

    Device Control is a brand new feature of the Myriota Network, which allows you to send messages from the Myriota Cloud to your Myriota-enabled devices in the field. It is available in SDK 2.0.0 and greater.

    The Device Control feature makes use of the Myriota Network downlink on the UHF band to transmit messages to a specified Myriota Module, allowing that device to be controlled, or reconfigured as required.

    Right now, the downlink path of the network is already used extensively to deliver Myriota network updates to devices. These updates are essential for keeping Myriota-enabled devices in sync with the Network such as:

    • informing Modules of the current time
    • informing Modules about changes in the Myriota constellation
    • updating satellite locations and communication channels
    • providing regulatory permission updates

    We are now opening up access to the downlink path, so you can send your own messages.

    For more information on how the Myriota Network downlink is used today, see our Downlink article.

    For more information on the downlink band, frequencies, and RF requirements, see the Myriota Antenna Design Guide.

    How does Device Control work?

    1. Device Control messages are scheduled for transmission to a Myriota-enabled device in the field using either the Cloud API or Device Manager UI.
    2. Once scheduled, a control message is queued on the Myriota Cloud for the next available upload opportunity to the Myriota satellite constellation.
    3. Once in the constellation, the control message is downlinked to the target device, where it is received and processed.

     

    [Back to Top]

     

    Sending Messages

    How can I send a Device Control message?

    Device Control messages can be sent to your Myriota enabled device using the new Device Control Cloud API.

    Our Code Examples provide more detail on how to use the Cloud API to create, manage, and send control messages.

    We have also enabled Device Control messages to be sent via a UI in Device Manager. The screenshot below shows the Send Control Message button and Control Message History for a selected Device.

    DeviceManager-DC1a.png

    To send a Device Control message via Device Manager:

    1. Click on the Control Message button
    2. Enter a hexadecimal string (up to 20 bytes) or,
    3. Upload a file with your message
      • The file must contain 20 bytes or less of raw data

    Uploaded files are treated as raw bytes and converted to hexadecimal; for example, 0100 encoded in a text file would be converted to hex 00010000, 0100 in a binary file would be converted to hex 04.

    How big are Device Control messages?

    Device control messages have a maximum size of 20 bytes.

    How often can I send Device Control messages?

    You can schedule one Device Control message, per device, per 24 hour period, for a total of 4 devices.

     

    [Back to Top]

     

    Receiving Messages

    How do I get my hardware ready for receiving Device Control messages?

    If you have already developed and Myriota-certified your own integrated device, then you have a working RX path as part of your antenna system. This is great news, as it means that providing the RX performance of your device is suitable, you have already done 90% of the work and can make use of the Device Control feature with no hardware or RF changes.

    The current Myriota Certification program requires a minimum RX success rate of 5%, which is sufficient for your device to successfully receive Myriota network updates, but not sufficient for making use of the new Device Control feature.

    To make use of the Device Control feature, we require that your device has a minimum RX success rate of 20%.

    If your device does not meet this minimum criterion, we can help you to improve the RX performance of your device, or we can assist you to use a Myriota Sense&Locate device to enable you to start exploring and integrating the feature into your user application.

    Other awesome benefits to increasing your RX success rate:

    • Devices will respond to network changes more quickly, as devices with low RX success rates may require more downlink attempts to successfully receive a network update
    • Receive performance is a contributing factor to power consumption, and a higher RX success rate can help extend the battery life of the device

    If you are using a Myriota device such as the Sense&Locate, Developer Toolkit or the Myriota Mouse, you have a high performing RX path and are good to go on the hardware front!

    How do I get my user application ready for receiving Device Control messages?

    Your user application can be updated to make use of the new ReceiveMessage API.

    Check out the receive example for a simple example of how to do this.

    How long will it take for a Device Control message to be received at my device?

    You can expect 90% of Device Control messages to arrive within 36 hours, with a median latency of 24 hours.

    How will I know whether a Device Control message has actually been received?

    The Control Message History UI in Device Manager (as shown in the screenshot above) provides visibility of diagnostic information about Device Control messages sent to each device. It does not, at this stage, provide visibility of whether a device has received the message. 

    Device Manager, Control Messages History, includes the following details:

    • ID - Device Control message ID
    • Status - Device Control message status. Pending, the message has been uploaded to the Myriota Cloud. Active, the message is in transit to or from space via the Myrota Network. Complete, the message has been transmitted to your device.
    • Created - Time the message was created and uploaded to the Myriota Cloud.
    • TransmitStart - The earliest expected message transmission time (from satellite to device).
    • TransmitEnd - The latest expected message transmission time (from satellite to device).

    We have provided an receive example User App that will send the first 10 bytes of your control message and its timing information back to the Myriota Network as an uplink message. Once this uplink message is visible at your Destination you can determine when your particular message arrived at the targeted device.

    Will receiving Device Control messages impact the expected battery life of my device?

    When receiving Device Control messages the receiver is turned on more often and therefore, there is a mild increase in energy consumption by the Myriota Module of about 10% (assuming your application uses 1 Device Control message and 1 uplink message per day). 

     

    [Back to Top]

     

    Send & Receive Code Examples

    Sending control messages to your device

    See the Device Control Cloud API documentation for details of the examples below.

    Setup

    Create an API token via Device Manager then setup the host and header parameters used throughout the following examples.

    import requests
    HOST = "https://api.myriota.com"
    AUTH = { "Authorization": f"{token}" }

    List Control Messages

    Gets a list of current and previous control messages.

    r = requests.get(f"{HOST}/v1/control-messages", headers=AUTH)
    r.raise_for_status()
    r.json()

    {
      "Items": [
        {
          "Id": "af7e9f6c-8aa7-46ab-a567-2fc7c42fefaf",
          "Status": "Complete",
          "Updated": 1639315800,
          "ModuleId": "004705714e"
        },
        {
          "Id": "756d431d-b938-4b56-b781-b46d6f0d73d3",
          "Status": "Cancelled",
          "Updated": 1639402200,
          "ModuleId": "004705714e"
        }
      ]
    }

    Create a Control Message

    Creates a new control message in the Pending state. The message will transition into the Active state once it has been uploaded to the satellite constellation.

    d = {"ModuleId": "004705714e", "Message": b"Hello, Earth".hex()}
    r = requests.post(f"{HOST}/v1/control-messages", json=d, headers=AUTH)
    r.raise_for_status()
    r.json()

    {
      "Items": [
        {
          "Id": "0d262261-0eb9-4593-b365-b226c62fb232",
          "Status": "Pending",
          "Updated": 1639488600,
          "ModuleId": "004705714e"
        }
      ]
    }

    Cancel a Control Message

    Cancels control message while it is in the "Pending" state, causing it to transition to the "Cancelled" state. 

    message_id = "0d262261-0eb9-4593-b365-b226c62fb232"
    r = requests.put(f"{HOST}/v1/control-messages/{message_id}/cancel", headers=AUTH)
    r.raise_for_status()
    r.json()
    {
      "Items": [
       {
         "Id": "0d262261-0eb9-4593-b365-b226c62fb232",
         "Status": "Cancelled",
         "MessageId": 25582816,
         "ModuleId": "004705714e"
       }
     ]
    }

    Get a Control Message

    Get details for the specified message.

    message_id = "0d262261-0eb9-4593-b365-b226c62fb232"
    r = requests.get(f"{HOST}/v1/control-messages/{message_id}", headers=AUTH)
    r.raise_for_status()
    r.json()

    {
      "Items": [
        {
          "Id": "0d262261-0eb9-4593-b365-b226c62fb232",
          "Status": "Active",
          "Updated": 1639503000,
          "ModuleId": "004705714e"
        }
      ]
    }

     

    Receiving control messages at your device

    The OnReceiveMessage event and ReceiveMessage function can be used to receive Device Control messages sent to your module. The receive example (main.c), available in the examples/receive folder in the SDK, demonstrates the use of these functions.

    The example implements two jobs ReceiveJob and TransmitJob that execute at their own cadence. The TransmitJob uses the ScheduleMessage function to send the following information via the Myriota Network:

    1. time when the Device Control message was scheduled for transmission
    2. number of messages received by the device to date
    3. time when the most recent Device Control message was received
    4. first 10 bytes of the most recent received Device Control message

    Messages to the Myriota Network are scheduled periodically every 8 hours, i.e. 3 messages per day.

    The ReceiveJob schedules additional messages with the same format but only executes when a new Device Control message is received by the device. This is achieved with the following line in AppInit:

    ScheduleJob(ReceiveJob, OnReceiveMessage());

    The ReceiveJob wakes when an OnReceiveMessage event is triggered by an arriving Device Control message. The Device Control message is recovered using the ReceiveMessage function and printed as a hexadecimal string. The example then schedules a message for transmission as described above and includes the first 10 bytes of the newly received Device Control message and the time it was received by the device.

    To test Device Control using this receive example, install the SDK and build the application, then put your module outside with a clear view of the sky.

    Throughout the trial period we expect to release updates to the SDK approximately once every 2 months. We recommend deploying your device in a location where it can be easily accessed for the purpose of reprogramming and redeploying as SDK updates are available.

    Messages can be sent to your Myriota module via the Device Manager UI or using the new Device Control APIs. It typically takes around a day for a message to be received by your module.

    The receive example also prints the Device Control message on the debug port when it is received and schedules the first 10 bytes of the Device Control message for transmission back to the Myriota Network. These return messages can be retrieved from the Myriota Message Store (if this has been used for your device Destination) using the message_store.py script in the SDK tools folder, where <ID> is the module id of your device.  

    message_store.py query <ID> > messages.json

    A sample of messages.json is shown below:

    [
      {
        "Timestamp": 1689645509240,
        "Value": "b9f1b5640000cccccccccccccccccccccccccccc"
      },
      {
        "Timestamp": 1689684500997,
        "Value": "018ab6640100018ab66448656c6c6f2c20456172"
      }
    ]

    These messages can be unpacked using the unpack.py script in the SDK examples/receive folder.  

    cat messages.json | grep Value | awk '{print $2}' | tr -d '"' | unpack.py

    This will produce the following json output:

    [
      {
        "Timestamp": 1689645497,
        "CountReceive": 0,
        "TimestampReceive": null,
        "MessageReceive": null
      },
      {
        "Timestamp": 1689684481,
        "CountReceive": 1,
        "TimestampReceive": 1689684481,
        "MessageReceive": "48656c6c6f2c20456172"
      }
    ]

    The first message was scheduled before the device received a Device Control message as indicated by the CountReceive field being zero. Consequently, no receive time and message content are available (value null). The second record contains valid values for all fields. In this example the message Hello, Earth! was sent to the device. The hexadecimal message 48656c6c6f2c20456172 unpacks to Hello, Ear i.e. the first 10 bytes of Hello, Earth!.

    Note that in the receive example, if you send a Device Control message that is shorter than 10 bytes to your device, it will be padded with a cc pattern in the message returned back to the Myriota Network (this is typical behaviour for the Myriota Network, all user messages are 20 bytes in size). For example, sending Hello to the device results in the unpacked message

    "MessageReceive": "48656c6c6fcccccccccc"

    Device Control messages received by your device are not padded with cc; the hex message received by the device will contain only the data that was sent to it. 

    [Back to Top]

     

     

    Related articles