Skip to main content

RAW IMT

REST API for Sending and Receiving Iridium Messaging Transport (IMT)

note

Minimum version v1.8.0

Introduction

The RockREMOTE API allows users to interact with various endpoints to send, receive, acknowledge messages, retrieve topics, and send commands related to message handling.

API Endpoints

The API consists of the following endpoints:

  1. Send MO IMT (POST)

    • Endpoint: /api/public/imt/mo
    • Description: Sends a MO IMT to the specified topic.
    • Parameters:
      • topic: (optional) The topic ID of the IMT topic, if no ID is given the default topic 244 will be used.
      • message: The message content. The message should be encoded in base64 format.
      • skipQueue: A boolean, if set to 1/True it will priorities this IMT and placed to the front of the Queue, excluding any message currently being sent.
    • Returns: A JSON formatted string indicating unique ID of the IMT MO, this can be used to get the status of the IMT.
    • Errors:
      • TOPIC_NOT_PROVISIONED: The RockREMOTE is not provisioned with the topic requested.
      • PAYLOAD_TOO_LARGE: The payload given exceeds the 100 K limit of the IMT.
  2. Get MO IMT Status (GET)

    • Endpoint: /api/public/imt/mo
    • Description: Retrieves the status of a previously sent message.
    • Parameters:
      • messageId: The unique ID of the message.
    • Returns: A JSON formatted string indicating the status of the MO IMT messages it had the following states:
      • IMT_MO_STATE_QUEUED: The MO IMT is queued in the RockREMOTE database waiting to be sent.
      • IMT_MO_STATE_SENDING: The MO IMT has or is being passed to the Iridium modem to be sent.
      • IMT_MO_STATE_SENT: The MO IMT has been sent and received a acknowledgement from the Iridium modem.
      • IMT_MO_STATE_DROPPED: The MO IMT has been dropped as it failed to send with-in the given parameters defined in the Queue Configuration
      • IMT_MO_STATE_CANCELLED: The MO IMT has been cancelled by the user using the command specified below. Errors:
      • INVALID_MESSAGE_ID: The message ID given is incorrect or the RockREMOTE has purged the history of that message to free memory for new messages.
  3. Get MT IMT (GET)

    • Endpoint: /api/public/imt/mt
    • Description: Retrieves messages from the specified topic.
    • Parameters:
      • topicId: (optional) The topic ID of the IMT topic, if no ID is given the default topic 244 will be used.
    • Returns: A JSON formatted string indicating unique ID of the IMT MT, payload in base64 and the timestamp of when it was received.
    • Errors:
      • NO_MESSAGES: All messages have been acknowledged or none have been received.
  4. Acknowledge a MT IMT (POST)

    • Endpoint: /api/public/imt/mt/acknowledge
    • Description: Acknowledges receipt of a IMT MT.
    • Parameters:
      • messageId: The unique ID of the IMT MT return in the receive message explained above.
    • Returns: A JSON formatted string to indicate success or failure.
    • Errors:
      • INVALID_MESSAGE_ID: The message ID given is incorrect or the RockREMOTE has purged the history of that message to free memory for new messages.
  5. Retrieve List of IMT Topics (GET)

    • Endpoint: /api/public/imt/topics
    • Description: Retrieves the list of available topics.
    • Returns: A JSON formatted string including an array of IMT topics available for RAW IMT. Errors:
      • NO_TOPICS_PROVISIONED: There are no IMT topics provisioned on the RockREMOTE for RAW IMT.
  6. Send Command (POST)

    • Endpoint: /api/public/imt/command
    • Description: Sends a command related to message handling.
    • Parameters:
      • command: The command type. Supported values are CLEAR_MT_QUEUE, CLEAR_MO_QUEUE and CANCEL_MO.
      • topicId: (required for CLEAR_MT_QUEUE and CLEAR_MO_QUEUE) The unsigned integer representing the topic ID.
      • messageId: (required for CANCEL_MO) The unique ID of the message to cancel.
    • Errors:
      • MO_CANCELLATION_FAILED: Failed to cancel the MO IMT, this usually means the message is too far in the sending process.
      • INVALID_MESSAGE_ID: The RockREMOTE does not know about this message ID.
      • TOPIC_NOT_PROVISIONED: The RockREMOTE is not provisioned with the topic specified.

Usage

Examples

  1. Send MO IMT (POST)

    • Example Request:
      MSG=$(echo -n "Hello World!" | openssl base64 -A)
      curl -X POST curl -X -d "topicId=80&message=$MSG" POST http://<RockREMOTE IP>:8080/api/public/imt/mo
    • Example Response:
    {"status":true,"messageId":"28","errors":[]}
  2. Get MO IMT Status (GET)

    • Example Request:
       curl -X GET http://<RockREMOTE IP>:8080/api/public/imt/mo?messageId=28
      • Example Response:
      {"status":true,"imtStatus":{"topic":80,"at":{"date":{"Day":1,"Month":3,"Year":2024},"time":{"Hour":8,"Minute":39,"Second":27}},"state":"IMT_MO_STATE_SENT"},"errors":[]}
  3. Receiving MT IMT (GET)

    • Example Request:
      curl -X GET http://<RockREMOTE IP>:8080/api/public/imt/mt?topicId=80
      • Example Response:
      {"status":true,"messageId":"17","payload":"SGVsbG8gV29ybGQ=","at":{"date":{"Day":1,"Month":3,"Year":2024},"time":{"Hour":8,"Minute":39,"Second":39}},"errors":[]}
  4. Acknowledging a IMT MT (POST)

    • Example Request:
       curl -X POST -d "messageId=17" http://<RockREMOTE IP>:8080/api/public/imt/mt/acknowledge
      • Example Response:
      {"status":true,"errors":[]}
  5. Retrieve List of IMT Topics (GET)

    • Example Request:
       curl -X GET http://<RockREMOTE IP>:8080/api/public/imt/topics
      • Example Response:
      {"status":true,"topics":[{"id":80,"name":"Reflector_400465"},{"id":69,"name":"IOT_101020"},{"id":244,"name":"RAW"}],"errors":[]}
  6. Sending a command

    • Example Request:
       curl -X POST -d "command=CLEAR_MT_QUEUE&topicId=80" http://<RockREMOTE IP>:8080/api/public/imt/command
      • Example Response:
      {"status":true,"errors":[]}

Sending MT IMT

If the RockREMOTE is provisioned with the RAW IMT topic (244). It possible to send a MT IMT message using Cloudloop Data. This is not documented here and is covered under the Cloudloop Data documentation.

Error Handling

Any response code other than 200 should be treated as a disconnection or incorrect API schema.

Errors can occur when status code is 200, this will be indicated with status being set to false in the response JSON. There will also be one or more error string in the errors array.

Python script

raw-imt.py is a demo Python script which can be used for perform local API GET/POST request for RAW IMT plus some respond handling.

If the RockREMOTE is not on the standard IP of 192.168.250.1 the script will need updating. This is defined towards the top as RR_IP.

Examples of using the script

Help

python3 raw-imt.py --help

usage: raw-imt [-h] [--topic TOPIC] [--message MESSAGE] [--message-id MESSAGE_ID] [--skip-queue SKIP_QUEUE] [--command COMMAND]
{send,status,get,ack,topics,cmd}

REST API client for RAW IMT.

positional arguments:
{send,status,get,ack,topics,cmd}
Action to perform: send, status, get, ack, topics, or cmd

options:
-h, --help show this help message and exit
--topic TOPIC Topic ID
--message MESSAGE Message to send
--message-id MESSAGE_ID
Message ID
--skip-queue SKIP_QUEUE
Is set when sending a message it is sent with high priority to skip the queue
--command COMMAND Command: 1 for CLEAR_MT_QUEUE, 2 for CLEAR_MO_QUEUE, 3 for CANCEL_MO

Get RAW Topics

python3 raw-imt.py topics

Topics:
ID: 80
Name: Reflector_400465
ID: 69
Name: IOT_101020
ID: 244
Name: RAW

Sending a MO IMT

python3 raw-imt.py send --topic 80 --message "Hello World!"

Message ID: 1148

Getting a MO IMT Status

python3 raw-imt.py status --message-id 1148

Status:
Topic ID: 80
State: IMT_MO_STATE_SENT
Timestamp: 2024-3-8 12:55:45

Getting a MT IMT

python3 raw-imt.py get --topic 80

Message ID: 1085
Payload: Hello World!

Acknowledging a MT IMT

python3 raw-imt.py ack --message-id 1085

Message ID: 1085 has been acknowledged

Sending a command

python3 raw-imt.py cmd --command 1 --topic 80

Command was successful