Skip to main content

Application Layer Description

Summary​

The application layer protocol consists of messages composed of an Operation Code and a collection of parameters. Request and answer messages are defined. The asset will always send a request to the module. The module will reply with an answer.

An example of message request/answer exchanges between the asset and module.

img

Module Configuration Commands​

The module can be configured with the following requests/answers:

  • Configuration Write Request/Answer: CFG_WR / CFG_WA.
  • Wi-Fi Write Request/Answer: WIF_WR / WIF_WA.
  • Configuration Read Request/Answer: CFG_RR / CFG_RA.
  • Configuration Save Request/Answer: CFG_SR / CFG_SA.
  • Configuration Factory Reset Request/Answer: CFG_FR / CFG_FA.
  • Geolocation Write Request/Answer: GEO_WR / GEO_WA.

The configurations are stored in RAM (volatile memory) after the writes. A module reset will revert the settings to the previously saved (in NVM) values.

Settings are stored in non-volatile memory with the configuration save request. This will allow settings to persist across resets. The saved values include: module config, Wi-Fi config, and geolocation config. Note the exceptional message timeout for the CFG_SR is 1.5 sec.

The module’s Configuration Register allows the following to be set:

  • Report Message Acknowledgements: determines if the message acknowledgements from the satellite are reported to the asset or not. Messages are always acknowledged between the module and the satellite. This setting determines whether the module reports the ack to the asset or not.

    • If set to 1, the module notifies the asset with the EVT register, and the asset must clear the ack with SAK_RR (ack read) and SAK_CR (ack clear).
    • If set to 0, the module removes messages from the queue automatically as soon as they are ack’ed by the satellite.

  • Add Geolocation: the module accepts a latitude and longitude from the asset (see Geolocation Write Request). This setting determines whether the geolocation is added to the message for display in the portal.

    • If set to 1, the module sends the coordinates with the message. This uses 8 bytes of message space.
    • If set to 0, the module does not include coordinates with the message.

  • Enable Ephemeris: the module maintains information about the active satellites and expected pass windows, called ephemeris data. This ephemeris data is not useful when the module is considered mobile or positioned at high latitudes. For more information, refer to the user guide.

    • Set to 1 to enable ephemeris: the module uses the ephemeris information to plan satellite searches.
    • Set to 0 to disable ephemeris: the module searches continuously when there is data to send.

  • Enable Deep Sleep: This will determine whether the module goes into deep sleep mode when possible. If this is enabled, the module will need to be woken up by the WAKEUP pin before communicating on the asset interface. See the datasheet for the time required between wakeup and first communication on the UART.

    • Set to 1 to enable deep sleep. Be sure to use the WAKEUP pin in this case.
    • Set to 0 to disable deep sleep. The WAKEUP pin is not needed. In this case, normal sleep mode is used.

  • Message Acknowledgement Event Pin Mask: the EVT register contains a bit indicating a message acknowledgement is available. This mask bit determines whether the EVENT_NOTIF pin shows the state of the EVT register bit.

    • Set to 1 for the EVENT_NOTIF pin state to show the state of the EVT register satellite ack bit.
    • Set to 0 for the EVENT_NOTIF pin state to ignore the state of the EVT register satellite ack bit.

  • Reset Notification Event Pin Mask: the EVT register contains a bit indicating the module has reset. This mask bit determines whether the EVENT_NOTIF pin shows the state of the EVT register bit.

    • Set to 1 for the EVENT_NOTIF pin state to show the state of the EVT register reset notification bit.
    • Set to 0 for the EVENT_NOTIF pin state to ignore the state of the EVT register reset notification bit.

  • Command Available Event Pin Mask: the EVT register contains a bit indicating a downlink Command is available to be read by the asset. This mask bit determines whether the EVENT_NOTIF pin shows the state of the command available EVT register bit.

    • Set to 1 for the EVENT_NOTIF pin state to show the state of the EVT register command available bit.
    • Set to 0 for the EVENT_NOTIF pin state to ignore the state of the EVT register command available bit.

  • Message Transmission (Tx) Pending Event Pin Mask: the EVT register contains a bit indicating the module message buffer contains a message waiting to be sent. This mask bit determines whether the EVENT_NOTIF pin shows the state of the command available EVT register bit.

    • Set to 1 for the EVENT_NOTIF pin state to show the state of the EVT register Message Tx Pending bit.
    • Set to 0 for the EVENT_NOTIF pin state to ignore the state of the EVT register Message Tx Pending bit.

Note: the EVENT_NOTIF pin mask bits are AND’ed with their corresponding EVT register bits, and the results are OR’ed together to set the physical EVENT_NOTIF pin status.

The factory reset request will revert all settings to the default values. This affects module config, Wi-Fi config, and geolocation config.

The default values are:

  • Module Config (CFG_WR):
    • Message Acknowledgement = 1
    • Add Geolocation = 0
    • Enable Ephemeris = 1
    • Enable Deep Sleep = 0
    • Message Acknowledgement Event Pin Mask = 1
    • Reset Notification Event Pin Mask = 0
    • Command Available Event Pin Mask = 1
    • Message Transmission Pending Event Pin Mask = 0
  • Geolocation (GEO_WR):
    • Latitude = 0
    • Longitude = 0
  • Wi-Fi settings (WIF_WR):
    • SSID: null
    • Password: null
    • Token: null

The default configuration is usable out of the box with the Astronode S modules. The Wi-Fi DevKit requires the WIF_WR to be sent to provide the Wi-Fi details and access token.

Payload Identifier​

The Payload ID is provided by the asset when queueing a message. It is used to identify the message and link sequent events to it. It has the following constraints:

  • It is a 16-bit number.
  • The asset is free to choose any value, but
  • the same Payload ID cannot be used concurrently in the module queue.

If the asset attempts to queue a message with a Payload ID already in use, the DUPLICATE_ID error will be returned.

The Payload ID is present in many of the application layer messages, to identify the message that the action applies to.

A Payload ID can be re-used with a new message once the previous message using the same Payload ID is out of the queue (via a dequeue or satellite acknowledgement clear).

Acknowledgement Event Discussion​

The Astrocast network provides a powerful acknowledgement feature to guarantee delivery. In the satellite module case the acknowledgement means that the message reached the satellite. The message must still be transmitted to the ground station and the Astrocast backend. In the Wi-Fi DevKit case, the Astrocast backend acknowledges the message directly.

The configuration of the module allows acknowledgements to be enabled or disabled. Regardless of this setting, messages are always acknowledged between the module and the satellite/Wi-Fi backend. This setting affects how the acknowledgements are presented to the asset. If turned off, the message is removed from the queue as soon as the module receives the acknowledgement. If turned on (default is on), the message is kept in the queue until the user reads and confirms the acknowledgement.

If the module has a notification for the asset, the module will notify the asset by setting the event pin high. The nature of the event can then be checked using the Event Read Request EVT_RR.

An alternative to monitoring the status of the event pin is to poll the module using the Event Read Request EVT_RR.

If the event notification is active, the asset can determine the source of the event in EVT_RA. If it is a satellite acknowledgement, the module can read which message was acknowledged using the Satellite Acknowledge Read Request SAK_RR, and then clear the acknowledgement using a Satellite Acknowledge Clear Request SAK_CR.

Error Management​

If the asset sends a bad request, the answer will indicate an error. The answer will contain the Operation Code 0xFF, and a 16-bit code will indicate the source of the error. The error codes are described in the ERROR section of Commands Definition.

Note that in the error case, the answer message structure does not match the request's structure, but rather simply the Operation Code 0xFF, followed by a 16 bit error code.

Last updated on