Skip to main content

Serial Commands Definition

How to use this page

This page will describe the messages at the application layer level, without encapsulation and encoding. The transport layer describes the encapsulation and encoding, and this should be applied to messages from this application layer before sending them on the physical interface. For convenience, many full examples of the application layer and transport layer are shown in the examples page.

Operation Code List

The table below provides a list of Operational Codes as Request IDs and corresponding Answer IDs. The Naming conventions follow the table. The IDs are used in the protocol. The names are just for referring to the operations in this document.

Asset => ModuleModule => Asset
RequestAnswer
IDNameDescriptionIDNameDescription
0x05CFG_WRWrite configuration, and store in RAM0x85CFG_WAAnswer last configuration write operation
0x06WIF_WRWrite Wi-Fi settings, and store in RAM - Wi-Fi DK only0x86WIF_WAAnswer last Wi-Fi settings write operation - Wi-Fi DK only
0x07SSC_WRSatellite Search Configuration Write Request. Stored in RAM (never saved in NVM).0x87SSC_WAAnswer last Satellite Search Configuration write operation
0x10CFG_SRSave configuration in NVM request0x90CFG_SAAnswer last configuration save request
0x11CFG_FRFactory reset configuration request0x91CFG_FAAnswer last factory reset request
0x15CFG_RRRead configuration from RAM0x95CFG_RAAnswer last configuration read operation with values
0x17RTC_RRReal Time Clock read request0x97RTC_RAAnswer last RTC read request with module time
0x18NCO_RRNext Contact Opportunity read request0x98NCO_RAAnswer with the time to the next contact opportunity
0x19MGI_RRModule GUID read request0x99MGI_RAAnswer last Module GUID read with GUID
0x1AMSN_RRModule Serial Number read request0x9AMSN_RAAnswer last Module Serial Number read with Serial Number
0x1BMPN_RRModule Product Number read request0x9BMPN_RAAnswer last Module Product Number read with the Product Number
0x25PLD_EREnqueue uplink payload, and store in RAM (never saved in NVM)0xA5PLD_EAAnswer last uplink payload enqueue operation
0x26PLD_DRDequeue uplink payload0xA6PLD_DAAnswer last uplink payload dequeue operation
0x27PLD_FRClear (Free) all queued payloads0xA7PLD_FAAnswer last free queued payloads operation
0x35GEO_WRWrite geolocation longitude and latitude, and store in RAM.0xB5GEO_WAAnswer last geolocation write operation
0x45SAK_RRRead Acknowledgement0xC5SAK_RAAnswer with Acknowledgement information
0x46SAK_CRConfirm to the module that the Acknowledgement was properly decoded and can be deleted by the module0xC6SAK_CAAnswer last SAK_CR confirmation
0x47CMD_RRRead a command (downlink)0xC7CMD_RAAnswer last CMD_RR with command data
0x48CMD_CRConfirm to the module that the command was properly decoded and can be deleted by the module0xC8CMD_CAAnswer last CMD_CR
0x55RES_CRClear reset event0xD5RES_CAAnswer the reset clear request
0x60VAL_WRValidation Mode Write0xE0VAL_WAAnswer the Validation Mode Write Request
0x61TTX_SRTest Transmit Start Request0xE1TTX_SAAnswer the Test Transmit Start Request
0x62GPO_SRGPIO Set Request0xE2GPO_SAAnswer the GPIO Set Request
0x63GPI_RRGPIO Read Request0xE3GPI_RAAnswer the GPIO Read Request
0x64ADC_RRADC Read Request0xE4ADC_RAAnswer the ADC Read Request
0x65EVT_RRReads the event register0xE5EVT_RAAnswer indicates which events are currently pending
0x66CTX_SRContext Save Request - recommended before cutting power0xE6CTX_SAAnswer confirming Context Save Request
0x67PER_RRPerformance Counter Read Request0xE7PER_RAAnswer with Performance Counters in Type, Length, Value format
0x68PER_CRPerformance Counter Clear Request0xE8PER_CAAnswer confirming Performance Counter Clear Request
0x69MST_RRModule State Read Request0xE9MST_RAAnswer with details of the current Module State
0x6ALCD_RRLast Contact Details Read Request0xEALCD_RAAnswer with details of the Last Contact
0x6BEND_RREnvironment Details Read Request to evaluate RF environment0xEBEND_RAAnswer with details of the RF environment
0x6CHTX_SRHomologation Transmit Start Request (special firmware only)0xECHTX_SAAnswer confirming the HTX_SR
0xFFERRORAnswer a request reporting an error

Naming conventions are loosely described by the following description. Note that the naming is given for convenience and there are some overlaps (e.g. Free and Factory both use ‘F’):

  • ***_*R refers to Request.
  • ***_*A refers to Answer.
  • The letter R/A is usually the action related to the message:
    • ***_W* - Write,
    • ***_R* - Read,
    • ***_S* - Save,
    • ***_E* - Enqueue,
    • ***_D* - Dequeue,
    • ***_F* - Free or FactoryReset,
    • ***_C* - Confirm.
  • The 3-letter prefix describes the operation further:
    • CFG_** - Configuration,
    • WIF_** - Wi-Fi,
    • PLD_** - Payload,
    • GEO_** - Geolocation,
    • SAK_** - Satellite Acknowledgement (which applies to Wi-Fi as well),
    • CMD_** - Command,
    • EVT_** - Event.

Putting this all together gives requests/answers such as:

  • EVT_RR as Event Read Request,
  • EVT_RA as Event Read Answer.

The following sections discuss the usage of these requests/answers.

Firmware Version Compatibility

DescriptionCommand> 2.2.x> 2.3.x> 2.5.x> 2.8.x
Write configuration, and store in RAMCFG_W
Write Wi-Fi settings, and store in RAMWIF_W
Satellite Search Configuration WriteSSC_W
Save configuration in NVMCFG_S
Factory reset configurationCFG_F
Read configuration from RAMCFG_R
Real Time Clock readRTC_R
Next Contact Opportunity read (Ephemeris)EPH_R
Next Contact Opportunity read (Ephemeris)NCO_R
Module GUID readDGI_R
Module GUID readMGI_R
Module Serial NumberDSN_R
Module Serial NumberMSN_R
Module Product Number readMPN_R
Enqueue uplink payload in RAMPLD_E
Dequeue uplink payloadPLD_R
Clear (Free) all queued payloadsPLD_F
Write Geolocation longitude and latitudeGEO_W
Read AcknowledgementSAK_R
Confirm the AcknowledgementSAK_C
Read a CommandCMD_R
Confirm the CommandCMD_C
Clear Reset EventRES_C
Validation Mode WriteVAL_W
Test Transmit StartTTX_S
GPIO Set RequestGPO_S
GPIO Read RequestGPI_R
ADC Read RequestADC_R
Reads the Event RegisterEVT_R
Context SaveCTX_S
Performance Counter ReadPER_R
Performance Counter ClearPER_C
Module State ReadMST_R
Last Contact Details ReadLCD_R
Environment Details ReadEND_R
> 2.2.x> 2.3.x> 2.5.x> 2.8.x

Module Configuration

CFG_W Configuration Write

CFG_WR Request

Parameters are stored in RAM. Refer to CFG_S to store configuration in NVM. Refer to CFG_F to factory reset the configuration in RAM and NVM.

The mask bits determine which bits of the EVT register are OR’ed together and shown on the EVENT_NOTIF pin.

IDParameters
CFG_WR=0x053 bytes
Byte offsetFormatNameDescription
0.0BitSatellite Acknowledgement0 = Asset not informed of ack to satellite
1 = Asset informed of ack to satellite (default)
0.1BitAdd Geolocation0 = No Geolocation (default)
1 = Add Geolocation
0.2BitEnable Ephemeris0 = Disable Ephemeris
1 = Enable Ephemeris (default)
0.3BitDeep Sleep Mode0 = Deep sleep not used (default)
1 = Deep sleep is used
0.4-0.7Reserved - set to zeroReserved - set to zero
1.0-1.7Reserved - set to zeroReserved - set to zero
2.0BitSatellite Ack Event Pin Mask0 = EVT pin does not show EVT register Satellite Payload Ack bit state
1 = EVT pin shows EVT register Payload Ack bit state (default)
2.1BitReset Notification Event Pin Mask0 = EVT pin does not show EVT register Reset Event Notification bit state (default)
1 = EVT pin shows EVT register Reset Event Notification bit state
2.2BitCommand Available Event Pin Mask0 = EVT pin does not show EVT register Command Available Notification bit state
1 = EVT pin shows EVT register Command Available bit state (default)
2.3BitMessage Transmission (Tx) Pending Event Pin Mask0 = EVT pin does not show EVT register Msg Tx Pending bit state (default)
1 = EVT pin shows EVT register Msg Tx Pending bit state
2.4-2.7Reserved - set to zeroReserved - set to zero

CFG_WA Answer

IDParameters
CFG_WA=0x85None
note

To be notified on the event pin in case of reset of the module (and the possible loss of queued payloads in such an event):

  • Set the "Reset Notification Event Pin Mask" using CFG_W.
  • Save the config to non-volatile-memory using CFG_S.

WIF_W Wi-Fi Configuration Write

caution

Applies to Wi-Fi DevKit only.

The Wi-Fi dev kit requires 3 parameters to be set to communicate with the Astrocast backend:

  • WLAN_SSID = your Wi-Fi network SSID name. See the note below on acceptable characters.
  • WLAN_KEY = corresponding key (password) for your SSID. See the note below on acceptable characters.
  • AUTH_TOKEN = 96-byte Access Token generated in the Astrocast Portal.

The default settings are null for all 3 parameters.

Note on SSID and Key characters

The IEEE 802.11 Wi-Fi specification allows the SSID and key to include non-printable characters and null characters (0). The Wi-Fi development kit intentionally deviates from this, and only characters in the ASCII range 0x20 to 0x7E should be used, terminated with a null character. This includes 0-9, a-z, A-Z, and many symbols. This development kit will not work with SSIDs or keys that use characters outside this range. If this is a problem, please contact support.

If the module considers the format incorrect, it will return an error code FORMAT_NOT_VALID.

WIF_WR Request

The write request saves the configuration in RAM. Unless the Config Save Request CFG_SR is sent, these settings will be lost on the next reset.

Parameters

IDParameters
WIF_WR=0x06194 bytes
Byte offsetFormatNameDescription
0Int8[33] null terminated stringWLAN_SSIDWLAN SSID maximum 32 characters + null termination. Null terminate unused chars.
33Int8[64] null terminated stringWLAN_KEYSSID Key maximum 63 characters + null termination. Null terminate unused chars.
97Byte[97]AUTH_TOKENAPI authentication token for Astrocast backend via Wi-Fi module. Fixed size 96 bytes + null termination.

WIF_WA Answer

IDParameters
WIF_WA=0x86None

SSC_W Satellite Search Config Write

Since 2.5.0

This requests sets the satellite search period. It is intended to speed up satellite search attempts to allow specific tests, such as antenna performance tests. In normal operation the module should be left to manage its own search times.

The two parameters are:

  1. Search period: sets the time between satellite searches. This is an enumeration, with fixed options for times.
  2. Enable search without a queued message: normally a module will not search for a satellite if there is no message to send. This flag enables searching even if there is no message to send.

The 1st parameter, search period, is an enumeration with fixed time values. The module cannot search at arbitrary time periods. The period must be limited to certain values to reliably detect the satellites. The options are given in the table below.

The 2nd parameter effectively enables searching when there is no message to send. This is useful for characterising antennas or noise.

caution

This request should only be used in special circumstances. Allow the module to use its default settings for satellite search in most scenarios.

This request may be useful for test cases such as antenna performance characterisation. To achieve continuous searching without continuous transmission (which may incur charges and load the network), the search period could be set to 2 (2'755 ms) and enable searching without a message queued set to 1. This leads to a search every 2'755 ms without having to queue a message to upload. The Environment Details Read Request could be used to retrieve the last RSSI.

These settings are not stored in NVM. Upon module reset or wake from deep sleep, the setting will revert to the default value.

SSC_WR Request

IDParameters
SSC_WR=0x072 bytes

Parameters

Byte offsetFormatNameDescription
0UInt8Search Period EnumerationSee table below. Default 0
1.0BitEnable search without message queued1 = search without message queued. 0 (default) = only search when a message is queued
1.1-1.7Reserved
Search Period EnumerationTime (milliseconds)
017'905 (default)
11'377
22'755
34'132
415'150
517'905
623'414

Periods larger than 23'414 ms could lead to very poor detection performance when the satellites are in low power modes.

If the Search Period is invalid, the error PERIOD_INVALID is returned.

SSC_WA Answer

IDParameters
SSC_WA=0x87None

CFG_S Configuration Save

Store the current RAM configuration in NVM. This will write the current module configuration CFG_WR, Wi-Fi configuration WIF_WR (if applicable), and geolocation GEO_WR to NVM.

This implies that after the next reset of the module, the saved settings will be loaded into RAM and used.

caution

This answer has an exceptional maximum timeout of 1.5 seconds.

CFG_SR Request

IDParameters
CFG_SR=0x10None

CFG_SA Answer

IDParameters
CFG_SA=0x90None

CFG_F Factory Reset

CFG_FR Request

Revert the module settings to the default values. Load these defaults into RAM. Write the defaults into NVM.

caution

This answer has an exceptional maximum timeout of 1.5 seconds.

The default values are discussed in Application Layer Description

IDParameters
CFG_FR=0x11None

CFG_FA Answer

IDParameters
CFG_FA=0x91None

CFG_R Configuration Read

Reads the module information and configuration. This returns the configuration stored in RAM, which does not necessarily match the configuration stored in non-volatile memory.

CFG_RR Request

IDParameters
CFG_RR=0x15None

CFG_RA Answer

IDParameters
CFG_RA=0x958 bytes

Parameters

Byte offsetFormatNameDescription
0UInt8Product ID0-2: Reserved
3: Commercial Satellite Astronode
4: Commercial Wi-Fi Dev Kit
1UInt8Hardware revisionModule electronics version
2UInt8Firmware major versionUsed when there is a loss of compatibility with previous versions
3UInt8Firmware minor versionUsed when features are added in a backwards compatible manner
4UInt8Firmware revisionUsed when fixing bugs in a backwards compatible manner
5.0BitPayload Acknowledgement0 = Asset not informed of payload acks
1 = Asset is informed of payload acks (default)
Note: Least Significant bit (LSb) is right most
5.1BitAdd Geolocation0 = No Geolocation (default)
1 = Add Geolocation
5.2BitEphemeris Enabled0 = Ephemeris disabled
1 = Ephemeris enabled (default)
5.3BitDeep Sleep Mode Enabled0 = Deep sleep mode not used (default)
1 = Deep sleep mode is used
5.4-5.7ReservedReserved
6.0-6.7ReservedReserved
7.0BitPayload Ack Event Pin Mask enabled0 = EVT pin does not show EVT register Payload Ack bit state
1 = EVT pin shows EVT register Payload Ack bit state (default)
7.1BitReset Notification Event Pin Mask enabled0 = EVT pin does not show EVT register Reset Event Notification bit state (default)
1 = EVT pin shows EVT register Reset Event Notification bit state
7.2BitCommand Available Event Pin Mask enabled0 = EVT pin does not show EVT register Command Available bit state
1 = EVT pin shows EVT register Command Available bit state (default)
7.3BitMessage Transmission (Tx) Pending Event Pin Mask enabled0 = EVT pin does not show EVT register Msg Tx Pending bit state (default)
1 = EVT pin shows EVT register Msg Tx Pending bit state
7.4-7.7ReservedReserved

Module Information

RTC_R RTC Read

Reads the module’s real time clock information.

RTC_RR Request

IDParameters
RTC_RR=0x17None

RTC_RA Answer

The module responds with the actual RTC time in seconds counting from the Astrocast Epoch time 2018-01-01 00:00:00 UTC. The returned time is UTC time and has no knowledge of timezones.

The answer can be 0 in the following conditions:

  • Wi-Fi DevKit will always return 0.
  • Satellite DevKit will return 0 in the period between a power-on-reset (RTC domain reset) and the first satellite synchronisation. In this period the module does not know the time, and indicates this by returning 0.
IDParameters
RTC_RA=0x974 bytes

Parameters

Byte offsetFormatNameDescription
0UInt32RTC timeTime in seconds since 2018-01-01 00:00:00 UTC.

NCO_R Next Contact Opportunity Read

Since firmware version 2.5.0, previously EPH_R

This request provides the time, in seconds, until the next opportunity for communication with the Astrocast network.

This was previously named EPH_RR. The name has been updated to better reflect the function. The operation code and functionality have not changed.

NCO_RR Request

IDParameters
NCO_RR=0x18None

NCO_RA Answer

The answer can be 0 in the following conditions:

  • Wi-Fi DevKit will always return 0.
  • The module doesn't have information on the constellation network (it hasn't synced with the Astrocast Network yet).
  • Ephemeris data are disabled in CFG_W.
  • Ephemeris data are disabled for the constellation. This will happen when the network is mature.
  • The module is currently in a known satellite pass opportunity. i.e. The time until the next opportunity is zero, which is now.
IDParameters
NCO_RA=0x984 byte

Parameters

Byte offsetFormatNameDescription
0UInt32Time to next passTime in seconds until the start of the next pass opportunity.
note

A 0 result indicates that, if a message is queued, the module would immediately try to send it through the Astrocast Network. If the answer is non-zero, it would wait that amount of time before trying to send the message.

info

The ephemeris data will be disabled for the constellation when the network is mature. Users should expect this in the future. Applications should be designed to handle NCO_R always returning 0 in the future.

MGI_R Module GUID Read

Since firmware version 2.5.0, previously DGI_R

Request the module GUID. The GUID is a unique identifier that can be used to link the module to the data management portal.

The GUID is 16 bytes long (32 chars 0-f). It is usually separated into groups with dashes, and it is returned in this format in this request. The format, with dashes, is correct for making API queries with the data management platform.

An example is: a18bebf0-15dd-a3e3-903a-46006acfae8e

MGI_RR Request

IDParameters
MGI_RR=0x19None

MGI_RA Answer

IDParameters
MGI_RA=0x9936 bytes

Parameters

Byte offsetFormatNameDescription
0Int8[36]GUIDGUID with dashes and without null termination. 36 chars composed of 0-9, a-f (lowercase) and ‘-‘ (dash).

MSN_R Module Serial Number Read

Since firmware version 2.5.0, previously DSN_R

Request the Serial Number from the module.

The serial number is 16 chars long, composed of printable ASCII characters. The serial number is a unique number for each module.

An example is: DKW2114AS1000510

MSN_RR Request

IDParameters
MSN_RR=0x1ANone

MSN_RA Answer

IDParameters
MSN_RA=0x9A16 bytes

Parameters

Byte offsetFormatNameDescription
0Int8[16]Serial NumberSerial Number without a null termination.

MPN_R Module Product Number Read

Since firmware version 2.5.0Request the Product Number from the module.

The product number is up to 16 chars long, composed of printable ASCII characters. If shorter than 16 chars, it is null terminated. The product number identifies a product in the Astrocast family. An example is: AST50120-00 for the Astronode S. Or AST50131-00 for the Astronode S Wi-Fi DevKit.

MPN_RR Request

IDParameters
MPN_RR=0x1BNone

MPN_RA Answer

IDParameters
MPN_RA=0x9B16 bytes

Parameters

Byte offsetFormatNameDescription
0Int8[16]Product NumberProduct Number, with unused characters null terminated (\0)

Message Management

PLD_E Enqueue Payload

PLD_ER Request

The PLD_ER request allows the asset to place a payload in the module queue. As mentioned in application layer description, the module has a queue with capacity for 8 payloads. Payloads can be up to 160 bytes in length.

info

Payloads are not saved in non-volatile memory.

IDParameters
PLD_ER=0x25N + 2 bytes

Parameters

Byte offsetFormatNameDescription
0UInt16Payload IDAn identifier for the payload, chosen by the asset. It cannot match an existing Payload ID present in the module queue.
2Byte [N]Payload DataThe N bytes of the payload to send. N must be 160 bytes or less. See the note below.

The Payload ID is used to unambiguously refer to a specific payload in the PLD_EA response, SAK_RA and PLD_DA. To avoid any ambiguity, if the Payload ID in the PLD_ER is identical to one of a payload already present in the module queue, the module will respond with a DUPLICATE_ID error, and the new payload will not be queued.

If the payload length is above the specified value, the module will return a LENGTH_NOT_VALID error, and the payload will not be queued.

note

In early Astronode Firmware versions (2.3.0 and lower), the maximum length of the Payload Data depends on whether geolocation is activated in the module configuration.

In early firmware, the maximum length is 152 bytes if geolocation is activated. This has fallen away in newer versions.

In newer firmware (2.4.0 and later) the maximum length is 160 bytes regardless of the geolocation setting.

If 8 payloads are already queued in the module, a PLD_ER will return a BUFFER_FULL error, and the payload will not be queued. There are multiple options to free space in the queue:

  • If a payload was successfully sent to the satellite, the asset can read and confirm the payload acknowledgement using a SAK_RR (see SAK_C Read Satellite ACK).
  • The asset can decide to dequeue the oldest payload in the queue, even if it was not sent to the satellite, using the PLD_DR request.
  • The asset can remove all payloads from the queue using the PLD_FR request.

PLD_EA Answer

IDParameters
PLD_ER=0xA5Payload ID

Parameters

Byte offsetFormatNameDescription
0UInt16Payload IDThe Payload ID specified by the Asset in the PLD_ER.

PLD_D Dequeue Payload

PLD_DR Request

The PLD_DR request is used to dequeue the oldest payload present in the module’s payload queue.

IDParameters
PLD_DR=0x26None
info

If the payload queue is empty, the module will answer with a BUFFER_EMPTY error code.

PLD_DA Answer

If PLD_DR is successful, the PLD_DA answer is defined as:

IDParameters
PLD_DA=0xA62 bytes

Parameters

Byte offsetFormatNameDescription
0UInt16Payload IDThe ID of the payload removed from the module queue.

PLD_F Clear/Free Payloads

PLD_FR Request

The module's entire payload queue can be cleared with the Payload Free Request PLD_FR.

IDParameters
PLD_FR=0x27None
info

If the payload buffer is empty, the module will answer with a BUFFER_EMPTY error code.

PLD_FA Answer
IDParameters
PLD_FA=0xA7None

GEO_W Geolocation Write

GEO_WR Request

Latitude and longitude values are encapsulated in the payload if the Add Geolocation bit in the configuration is set to 1. If latitude and longitude values are not specified, and the Add Geolocation bit is 1, then default coordinates (0,0) would be used.

note

The end user is free to encapsulate geolocation data within the payload, without having to use this specific feature. The advantage of this feature is that the Astrocast portal will have knowledge of the location of the module, which can be useful for module management.

If this feature is enabled with the Add Geolocation bit, then the coordinates (8 bytes) will be added on top of the user data payload.

Note that these settings are stored in RAM. Storage the setting in NVM with the Config Save Request CFG_SR. Settings in RAM could be lost on a module reset.

Longitude and latitude are set using the GEO_WR request:

IDParameters
GEO_WR=0x358 bytes

Parameters

Byte offsetFormatNameDescription
0Int32LatitudeDegrees Latitude * 1E7
(i.e., latitude multiplied by 10'000'000)
Must be in the range -90° to 90°
4Int32LongitudeDegrees Longitude * 1E7
(i.e., longitude multiplied by 10'000'000)
Must be in the range -180° to 180°
info

If an invalid longitude or latitude are sent, both values are discarded, and an INVALID_POS error is returned.

GEO_WA Answer

IDParameters
GEO_WA=0xB5None

EVT_R Event Register Read

The EVT_RR request reads the event register.

If the value of the event register is greater than zero, and the EVENT pin mask set by CFG_WR is set, the module's EVENT pin on the asset interface will be high. The asset may poll this register periodically if the EVENT pin is not connected to the asset.

Note the event pin mask in CFG_WR to see how the event register is shown on the EVT pin.

In service level 1, the only events are: payload acknowledgement messages; and module resets.

In service level 2, a further 2 events are added: command available; and message transmit pending.

Further event types will be added to later service levels and reflected in this event register.

The Satellite Ack Available bit set to 1 indicates that an acknowledgement is available and can be read with SAK_RR and then cleared with SAK_CR. After clearing all acks, this bit will return to 0.

The Module Reset bit set to 1 indicates that the module has restarted. RES_CR would clear this bit. The payload queue is held in volatile memory, so the queue will be empty after a reset.

The Command Available bit set to 1 indicates that a command is available to be read with CMD_RR and then cleared with CMD_CR.

The Message Transmit Pending bit set to 1 indicates that the uplink message buffer is not empty, and that resetting or powering the device down would lead to data loss. The uplink message buffer may contain control messages in addition to data messages. Control messages are generated in response to downlink commands to the module. Power to the module should not be cut until this bit goes to 0.

EVT_RR Request

IDParameters
EVT_RR=0x65None

EVT_RA Answer

IDParameters
EVT_RA=0xE51 byte

Parameters

Byte offsetFormatNameDescription
0.0BitSatellite Ack AvailableA satellite payload acknowledgement is available to be read and confirmed
0.1BitModule ResetModule has reset
0.2BitCommand AvailableA command is available to be read and confirmed
0.3BitMessage Transmit PendingAn uplink message is present in the message queue, waiting to be sent, and module power should not be cut.
0.4-7Reserved

SAK_R Read Satellite ACK

SAK_RR Request

If the event register indicates a Satellite Acknowledgement is available, the acknowledgement can be read with the SAK_RR request.

IDParameters
SAK_RR=0x45None
info

If there are no ack’s available, the module will answer with a NO_ACK error code.

SAK_RA Answer

The module responds with a SAK_RA answer. If an acknowledgement is available, the message contains the payload ID of the acknowledged payload.

IDParameters
SAK_RA=0xC52 bytes

Parameters

Byte offsetFormatNameDescription
0UInt16Payload IDIdentifier for the payload, corresponding to the payload ID specified by the asset in the PLD_ER when the payload was queued.

SAK_C Clear Satellite ACK

Following on from a SAK_RR (Satellite Acknowledgement Read), a SAK_CR (Satellite Acknowledgement Clear) should be sent to complete the payload life cycle and clear the payload from the module payload queue. The SAK_CR must follow a prior SAK_RR/SAK_RA exchange.

SAK_CR Request

IDParameters
SAK_CR=0x46None
info

If the SAK_CR is sent without a corresponding prior SAK_RR request, the module will return an error with NO_ACK_CLEAR as the error code.

SAK_CA Answer

IDParameters
SAK_CA=0xC6None

Command Management

CMD_R Command Read

Since firmware version 2.8.0

CMD_RR Request

If the event register indicates a Command is available, the command can be read with the CMD_RR request.

IDParameters
CMD_RR=0x47None
info

If there are no commands available, the module will answer with a NO_COMMAND error code.

CMD_RA Answer

The module responds with a CMD_RA answer. If a command is available, the message contains the command payload and the created date.

The message will contain an N byte payload. N is fixed to 2 possible sizes: 8 or 40 bytes.

IDParameters
CMD_RA=0xC74 + N bytes

Parameters

Byte offsetFormatNameDescription
0UInt32Created DateIn seconds since 2018-01-01 00:00:00 UTC
4UInt8[N]PayloadN bytes of payload, where N is 8 or 40

CMD_C Command Clear

Since firmware version 2.8.0

Following on from a CMD_RR (Command Read), a CMD_CR (Command Clear) should be sent to remove the command from the Astronode buffer. The CMD_CR must follow a prior CMD_RR/CMD_RA exchange.

CMD_CR Request

IDParameters
CMD_CR=0x48None
info

If the CMD_CR is sent without a corresponding prior CMD_RR request, the module will return an error with NO_COMMAND_CLEAR as the error code.

CMD_CA Answer

IDParameters
CMD_CA=0xC8None

Manufacturing Commands

All manufacturing commands are supported since firmware version 2.8.0

VAL_W Validation Mode Write

The VAL_WR begins a validation mode session. This mode enables some special commands for test purposes only. Normal radio operations are disabled in validation mode. A reset is required to exit this mode.

info

All non-validation mode commands are disabled in this mode and will return an error code.

VAL_WR Request

IDParameters
VAL_WR=0x60None

VAL_WA Answer

IDParameters
VAL_WA=0xE0None

TTX_S Test Transmit Start

The TTX_SR begins a test transmission for manufacturing purposes, to check the antenna soldering. The module will output:

  • random symbols (PRBS9) in a loop
  • with the normal Astronode modulation
  • at the normal transmit power calibrated for the module
  • for the time specified, up to 30 seconds
  • at a frequency of 1.6435 GHz. This frequency is selected to be in the middle of the L-band, and is not the frequency used by the module for satellite communication.

To effectively view this on a spectrum analyser, a span of 5kHz is recommended.

To ensure compliance with the rules of the L-band spectrum, each module is only allowed 10 test transmissions over the course of its life. Use them carefully.

caution

After 10 test transmissions this request will return an error.

TTX_SR Request

IDParameters
TTX_SR=0x611 Byte

Parameters

Byte offsetFormatNameDescription
0ByteTx time (sec)Start a test transmission for up to 30 seconds

TTX_SA Answer

IDParameters
TTX_SA=0xE11 Byte

Parameters

Byte offsetFormatNameDescription
0ByteTransmissions remainingNumber of transmissions remaining after the one request by the previous TTX_SR

GPO_S GPIO Set

The GPO_SR sets a given pin to a given state.

info

Validation mode must be enabled to use this command.

GPO_SR Request

IDParameters
GPO_SR=0x622 Bytes

Parameters

Byte offsetFormatNameDescription
0BytePin ID0 = EVENT_NOTIF, 1 = ANTN_USE
1ByteState0 = OFF, 1 = ON

GPO_SA Answer

IDParameters
GPO_SA=0xE20 Byte

GPI_R GPIO Read

The GPI_RR reads the state of a given pin.

info

Validation mode must be enabled to use this command.

GPI_RR Request

IDParameters
GPI_RR=0x631 Byte

Parameters

Byte offsetFormatNameDescription
0BytePin ID2 = WAKEUP

GPI_RA Answer

IDParameters
GPI_RA=0xE31 Byte

Parameters

Byte offsetFormatNameDescription
0ByteState0 = OFF, 1 = ON

ADC_R ADC Read

The ADC_RR reads the analog voltage in mV on the 3.3V rail.

info

Validation mode must be enabled to use this command.

ADC_RR Request

IDParameters
ADC_RR=0x640 Byte

ADC_RA Answer

IDParameters
ADC_RA=0xE44 Bytes

Parameters

Byte offsetFormatNameDescription
0Uint32Analog Voltage3.3V rail voltage in mV

Advanced Commands

RES_C Clear Reset Event

The RES_CR clears the Module Reset bit in the Event Register.

On start up, the module indicates a reset event by setting the Module Reset bit in the Event Register and, depending on the mask setting in the config register, setting the EVT pin to 1.

RES_CR Request

IDParameters
RES_CR=0x55None

RES_CA Answer

IDParameters
RES_CA=0xD5None

CTX_S Context Save

Since firmware version 2.5.0

Save the current context to NVM. It is recommended to do this before powering off the module or triggering a reset with the reset pin. This writes the performance counter to NVM and stores the last contact details in the RTC backup domain.

caution

This answer has an exceptional maximum timeout of 1.5 seconds.

CTX_SR Request

IDParameters
CTX_SR=0x66None

CTX_SA Answer

The answer confirms that the counters have been saved.

IDParameters
CTX_SA=0xE6None

PER_R Performance Counters Read

Since firmware version 2.5.0

Performance counters allow certain module operations to be tracked in time. The counters are stored in NVM and incremented over the life of the module. They can be reset with PER_CR. For example, the 'Queued Message Count' will increment every time a PLD_ER succeeds, over the life of the module, or until a counter reset with PER_CR,

Counters are automatically saved before entering deep sleep (not normal sleep) or 24h since the last save. To save them before cutting the module power or resetting, use CTX_SR.

PER_RR Request

IDParameters
PER_RR=0x67None

PER_RA Answer

Performance counters are returned as multiple Type, Length, Value (TLV) combinations. This allows counters to be added or removed from the module in the future. The list of counters and the number returned may change with future firmware releases. The Type and Length definitions will be fixed.

IDParameters
PER_RA=0xE7N bytes

Parameters

Byte offsetFormatNameDescription
0UInt81st Performance Counter Type (T)Describes the type - see below
1UInt8Length of the 1st counter (L)Number of bytes
2L Byte ValueValue of the 1st counter (V)Value. If Length > 1: little endian format
3 + (Lprev)...TLV value scheme repeats
Counter TypeExpected LengthData TypeValueDescription
0x014UInt32Satellite search phase countHow many times the module has entered the satellite search phase. This may consist of multiple satellite detection operations
0x024UInt32Satellite detection operation countEach satellite search phase may contain multiple satellite detection operations, as multiple frequencies are checked
0x034UInt32Signalling demodulation phase countHow many times the module has entered the signalling demodulation phase with a detected satellite. This may consist of multiple signalling demodulation attempts
0x044UInt32Signalling demodulation attempt countHow many signalling demodulations have been attempted
0x054UInt32Signalling demodulation success countHow many signalling demodulations have succeeded
0x064UInt32Acknowledgement demodulation attempt countHow many ack demodulations have been attempted
0x074UInt32Acknowledgement demodulation success countHow many ack demodulations have succeeded
0x084UInt32Queued message countThe number of messages that have been queued
0x094UInt32Dequeued unacked message countCount of un-acknowledged messages dequeued. Dequeuing or freeing acked messages will not increment this count.
0x0A4UInt32Acknowledged message countThe number of messages that have been ack'ed by satellites
0x0B4UInt32Sent fragment countThe number of fragments that have been sent to satellites
0x0C4UInt32Acknowledged fragment countThe number of fragments that have been ack'ed by satellites
0x0D4UInt32Command demodulation attempt countHow many command demodulations have been attempted
0x0E4UInt32Command demodulation success countHow many command demodulations have been successful

PER_C Performance Counters Clear

Since firmware version 2.5.0

Reset the performance counters to zero. This additionally saves the counters to the NVM.

caution

This answer has an exceptional maximum timeout of 1.5 seconds.

PER_CR Request

IDParameters
PER_CR=0x68None

PER_CA Answer

The answer confirms that the counters have been zeroed.

IDParameters
PER_CA=0xE8None

MST_R Module State Read

Since firmware version 2.5.0

The Module State Read gives information about the message queue (current state of the queue) and the last reset reason.

MST_RR Request

IDParameters
MST_RR=0x69None

MST_RA Answer

Module State details are returned as multiple Type, Length, Value (TLV) combinations. This allows details to be added or removed from the module in the future. The list of details and the number returned may change with future firmware releases. The Type and Length definitions will be fixed.

IDParameters
MST_RA=0xE9N bytes

Parameters

Byte offsetFormatNameDescription
0UInt81st Module State Detail Type (T)Describes the type - see below
1UInt8Length of the 1st detail (L)Number of bytes
2L Byte ValueValue of the 1st detail (V)Value. If Length > 1: little endian format
3 + (Lprev)...TLV value scheme repeats
Module State Details TypeExpected LengthData TypeValueDescription
0x411UInt8Messages in queueIncludes ack'ed messages waiting to be read/confirmed
0x421UInt8Ack'ed messages in queueMessages that have been ack'ed by satellites
0x431UInt8Last reset reasonSee the table below for reasons
0x444UInt32UptimeNumber of seconds since last reset.

Note: uptime is a count up from the last reset. If the device wakes from deep sleep, it is considered a reset, and the uptime will reset to zero. If the device weeks from normal sleep, it is not a reset, and the uptime will not reset to zero.

Reset Reason TypeReset ReasonDescription
0x00No resetNo reset has been detected
0x01General resetPower was applied and the module started up; or rising edge on the reset pin; or wake up from deep-sleep
0x02Software resetModule software intentionally reset
0x03Watchdog resetModule software unintentionally reset
0x04Brown outModule supply voltage dropped and a reset was triggered

LCD_R Last Contact Details Read

Since firmware version 2.5.0

The Last Contact Details Read gives information about the last satellite contact.

LCD_RR Request

IDParameters
LCD_RR=0x6ANone

LCD_RA Answer

Last contact details are returned as multiple Type, Length, Value (TLV) combinations. This allows details to be added or removed from the module in the future. The list of details and the number returned may change with future firmware releases. The Type and Length definitions will be fixed.

IDParameters
LCD_RA=0xEAN bytes

Parameters

Byte offsetFormatNameDescription
0UInt81st Last Contact Detail Type (T)Describes the data type - see below
1UInt8Length of the 1st detail (L)Number of bytes
2L Byte ValueValue of the 1st detail (V)Value. If Length > 1: little endian format
3 + (Lprev)...TLV value scheme repeats
LPD Type IDExpected LengthData TypeValueDescription
0x514UInt32Time of start of last contact (sec since 2018-01-01 00:00:00 UTC)The satellite contact starts when the module successful demodulates the satellite signalling for the first time. Zero if there has been no contact
0x524UInt32Time of end of last contact (sec since 2018-01-01 00:00:00 UTC)The satellite contact ends when the module last demodulated signalling successfully. Zero if there has been no contact. If contact is ongoing, this will reflect the last successful demodulation time
0x531UInt8Peak RSSI of last passExpected range 0-30 for most environments
0x544UInt32Time of peak RSSI in last contact (sec since 2018-01-01 00:00:00 UTC)

END_R Environment Details Read

Since firmware version 2.5.0

The Environment Details Read gives information about the module's environment

END_RR Request

IDParameters
END_RR=0x6BNone

END_RA Answer

Environment details are returned as multiple Type, Length, Value (TLV) combinations. This allows details to be added or removed from the module in future. The list of details and the number returned may change with future firmware releases. The Type and Length definitions will be fixed.

IDParameters
END_RA=0xEBN bytes

Parameters

Byte offsetFormatNameDescription
0UInt81st Environment Detail Type (T)Describes the data type - see below
1UInt8Length of the 1st detail (L)Number of bytes
2L Byte ValueValue of the 1st detail (V)Value. If Length > 1: little endian format
3 + (Lprev)...TLV value scheme repeats
Env Detail Type IDExpected LengthData TypeValueDescription
0x611UInt8Last MAC ResultValues are described in the table below.
0x621UInt8Last satellite search peak RSSIThe maximum RSSI seen in the last search. If multiple channels are checked, it is the maximum value. Expected range 0-30 for most environments
0x634UInt32Time since last satellite search (sec)This is a relative time (seconds since) because the absolute time may not be known by the module
MAC ResultDescription
0None
1Success
2Satellite not detected
3Sync demodulation fail
4Signalling demodulation fail
5Ack signalling fail
6No ack in frame
7Error
8Timeout
9Blacklisted
10Test Satellite
11Satellite Low Power Interruption

HTX_S Homologation Transmit Start

HTX_SR allows homologation testing to be done in transmit mode. The following options are available:
  • Duration: in seconds. To stop early, reset the module.
  • Frequency: the testable options are limited to low, middle and high frequencies in the L-band. The exact details are available from support.
  • Modulation: the output can be modulated or unmodulated.

The output power is fixed to the value calibrated for the module.

A PBRS9 pseudorandom byte sequence is transmitted for the modulated data.

The command is only available when validation mode is enabled on the module.

caution

This command is only available on special modules obtained from Astrocast for homologation. The command is not available in normal firmware.

HTX_SR Request

IDParameters
HTX_SR=0x6C1 Byte

Parameters

Byte offsetFormatNameDescription
0UInt16Tx time (sec)Transmit for this amount of time
2UInt8Freq EnumerationSelect the L-band Tx frequency as low, middle, or high
3.0BitModulation0 = unmodulated (carrier wave); 1 = modulated
3.1-3.7ReservedSet to zero
Freq EnumerationFrequency Selected
0Low
1Middle
2High

HTX_SA Answer

The answer indicates the transmission will start. Otherwise, an error will be returned.

IDParameters
HTX_SA=0xECEmpty

Errors

The structure of an error answer is defined here:

IDParameters
ERROR=0xFFUInt16 Error Code

Parameters

Byte offsetFormatNameDescription
0UInt16Error CodeSee the list of error code in Table 3

Table 3 - Error code list

Error codeError typeNameDescription
0x0001COMMCRC_NOT_VALIDDiscrepancy between provided CRC and expected CRC.
0x0011COMMLENGTH_NOT_VALIDMessage length is not valid for the operation code, or the message exceeds the maximum length for a frame.
0x0121COMMOPCODE_NOT_VALIDInvalid Operation Code used.
0x0122COMMARG_NOT_VALIDInvalid argument used.
0x0123COMMFLASH_WRITING_FAILEDFailed to write to the flash.
0x0124COMMDEVICE_BUSYDevice is busy.
0x0601WIF_ERFORMAT_NOT_VALIDAt least one of the fields (SSID, password, token) is not composed of exclusively printable standard ASCII characters (0x20 to 0x7E).
0x0701SSC_ERPERIOD_INVALIDThe Satellite Search Config period enumeration value is not valid
0x2501PLD_ERBUFFER_FULLFailed to queue the payload because the sending queue is already full.
0x2511PLD_ERDUPLICATE_IDFailed to queue the payload because the Payload ID provided by the asset is already in use in the module queue.
0x2601PLD_DRBUFFER_EMPTYFailed to dequeue a payload from the buffer because the buffer is empty
0x3501GEO_WRINVALID_POSFailed to update the geolocation information. Latitude and longitude fields must in the range [-90,90] degrees and [-180,180] degrees, respectively.
0x4501SAK_RRNO_ACKNo satellite acknowledgement available for any payload.
0x4601SAK_CRNO_ACK_CLEARNo payload ack to clear, or it was already cleared.
0x4701CMD_RRNO_COMMANDNo command is available.
0x4801CMD_CRNO_COMMAND_CLEARNo command to clear, or it was already cleared.
0x6101TTX_SRMAX_TX_REACHEDFailed to test Tx due to the maximum number of transmissions being reached.