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":[]}

  1. 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":[]}

  2. 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":[]}

  3. 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":[]}

  4. 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