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 => Module			Module => Asset
Request			Answer
ID	Name	Description	ID	Name	Description
0x05	CFG_WR	Write configuration, and store in RAM	0x85	CFG_WA	Answer last configuration write operation
0x06	WIF_WR	Write Wi-Fi settings, and store in RAM - Wi-Fi DK only	0x86	WIF_WA	Answer last Wi-Fi settings write operation - Wi-Fi DK only
0x07	SSC_WR	Satellite Search Configuration Write Request. Stored in RAM (never saved in NVM).	0x87	SSC_WA	Answer last Satellite Search Configuration write operation
0x10	CFG_SR	Save configuration in NVM request	0x90	CFG_SA	Answer last configuration save request
0x11	CFG_FR	Factory reset configuration request	0x91	CFG_FA	Answer last factory reset request
0x15	CFG_RR	Read configuration from RAM	0x95	CFG_RA	Answer last configuration read operation with values
0x17	RTC_RR	Real Time Clock read request	0x97	RTC_RA	Answer last RTC read request with module time
0x18	NCO_RR	Next Contact Opportunity read request	0x98	NCO_RA	Answer with the time to the next contact opportunity
0x19	MGI_RR	Module GUID read request	0x99	MGI_RA	Answer last Module GUID read with GUID
0x1A	MSN_RR	Module Serial Number read request	0x9A	MSN_RA	Answer last Module Serial Number read with Serial Number
0x1B	MPN_RR	Module Product Number read request	0x9B	MPN_RA	Answer last Module Product Number read with the Product Number
0x25	PLD_ER	Enqueue uplink payload, and store in RAM (never saved in NVM)	0xA5	PLD_EA	Answer last uplink payload enqueue operation
0x26	PLD_DR	Dequeue uplink payload	0xA6	PLD_DA	Answer last uplink payload dequeue operation
0x27	PLD_FR	Clear (Free) all queued payloads	0xA7	PLD_FA	Answer last free queued payloads operation
0x35	GEO_WR	Write geolocation longitude and latitude, and store in RAM.	0xB5	GEO_WA	Answer last geolocation write operation
0x45	SAK_RR	Read Acknowledgement	0xC5	SAK_RA	Answer with Acknowledgement information
0x46	SAK_CR	Confirm to the module that the Acknowledgement was properly decoded and can be deleted by the module	0xC6	SAK_CA	Answer last SAK_CR confirmation
0x47	CMD_RR	Read a command (downlink)	0xC7	CMD_RA	Answer last CMD_RR with command data
0x48	CMD_CR	Confirm to the module that the command was properly decoded and can be deleted by the module	0xC8	CMD_CA	Answer last CMD_CR
0x55	RES_CR	Clear reset event	0xD5	RES_CA	Answer the reset clear request
0x60	VAL_WR	Validation Mode Write	0xE0	VAL_WA	Answer the Validation Mode Write Request
0x61	TTX_SR	Test Transmit Start Request	0xE1	TTX_SA	Answer the Test Transmit Start Request
0x62	GPO_SR	GPIO Set Request	0xE2	GPO_SA	Answer the GPIO Set Request
0x63	GPI_RR	GPIO Read Request	0xE3	GPI_RA	Answer the GPIO Read Request
0x64	ADC_RR	ADC Read Request	0xE4	ADC_RA	Answer the ADC Read Request
0x65	EVT_RR	Reads the event register	0xE5	EVT_RA	Answer indicates which events are currently pending
0x66	CTX_SR	Context Save Request - recommended before cutting power	0xE6	CTX_SA	Answer confirming Context Save Request
0x67	PER_RR	Performance Counter Read Request	0xE7	PER_RA	Answer with Performance Counters in Type, Length, Value format
0x68	PER_CR	Performance Counter Clear Request	0xE8	PER_CA	Answer confirming Performance Counter Clear Request
0x69	MST_RR	Module State Read Request	0xE9	MST_RA	Answer with details of the current Module State
0x6A	LCD_RR	Last Contact Details Read Request	0xEA	LCD_RA	Answer with details of the Last Contact
0x6B	END_RR	Environment Details Read Request to evaluate RF environment	0xEB	END_RA	Answer with details of the RF environment
0x6C	HTX_SR	Homologation Transmit Start Request (special firmware only)	0xEC	HTX_SA	Answer confirming the HTX_SR
			0xFF	ERROR	Answer 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

Description	Command	> 2.2.x	> 2.3.x	> 2.5.x	> 2.8.x
Write configuration, and store in RAM	CFG_W	✅	✅	✅	✅
Write Wi-Fi settings, and store in RAM	WIF_W	✅	✅	✅	✅
Satellite Search Configuration Write	SSC_W			✅	✅
Save configuration in NVM	CFG_S	✅	✅	✅	✅
Factory reset configuration	CFG_F	✅	✅	✅	✅
Read configuration from RAM	CFG_R	✅	✅	✅	✅
Real Time Clock read	RTC_R	✅	✅	✅	✅
Next Contact Opportunity read (Ephemeris)	EPH_R		✅
Next Contact Opportunity read (Ephemeris)	NCO_R			✅	✅
Module GUID read	DGI_R	✅	✅
Module GUID read	MGI_R			✅	✅
Module Serial Number	DSN_R	✅	✅
Module Serial Number	MSN_R			✅	✅
Module Product Number read	MPN_R			✅	✅
Enqueue uplink payload in RAM	PLD_E	✅	✅	✅	✅
Dequeue uplink payload	PLD_R	✅	✅	✅	✅
Clear (Free) all queued payloads	PLD_F	✅	✅	✅	✅
Write Geolocation longitude and latitude	GEO_W	✅	✅	✅	✅
Read Acknowledgement	SAK_R	✅	✅	✅	✅
Confirm the Acknowledgement	SAK_C	✅	✅	✅	✅
Read a Command	CMD_R				✅
Confirm the Command	CMD_C				✅
Clear Reset Event	RES_C	✅	✅	✅	✅
Validation Mode Write	VAL_W				✅
Test Transmit Start	TTX_S			✅	✅
GPIO Set Request	GPO_S				✅
GPIO Read Request	GPI_R				✅
ADC Read Request	ADC_R				✅
Reads the Event Register	EVT_R	✅	✅	✅	✅
Context Save	CTX_S			✅	✅
Performance Counter Read	PER_R			✅	✅
Performance Counter Clear	PER_C			✅	✅
Module State Read	MST_R			✅	✅
Last Contact Details Read	LCD_R			✅	✅
Environment Details Read	END_R			✅	✅
		> 2.2.x	> 2.3.x	> 2.5.x	> 2.8.x

Module Configuration

CFG_W Configuration Write

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.

CFG_WR Request

ID	Parameters
CFG_WR=0x05	3 bytes

Parameters

Byte offset	Format	Name	Description
0.0	Bit	Satellite Acknowledgement	0 = Asset not informed of ack to satellite 1 = Asset informed of ack to satellite (default)
0.1	Bit	Add Geolocation	0 = No Geolocation (default) 1 = Add Geolocation
0.2	Bit	Enable Ephemeris	0 = Disable Ephemeris 1 = Enable Ephemeris (default)
0.3	Bit	Deep Sleep Mode	0 = Deep sleep not used (default) 1 = Deep sleep is used
0.4-0.7		Reserved - set to zero	Reserved - set to zero
1.0-1.7		Reserved - set to zero	Reserved - set to zero
2.0	Bit	Satellite Ack Event Pin Mask	0 = EVT pin does not show EVT register Satellite Payload Ack bit state 1 = EVT pin shows EVT register Payload Ack bit state (default)
2.1	Bit	Reset Notification Event Pin Mask	0 = 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.2	Bit	Command Available Event Pin Mask	0 = EVT pin does not show EVT register Command Available Notification bit state 1 = EVT pin shows EVT register Command Available bit state (default)
2.3	Bit	Message Transmission (Tx) Pending Event Pin Mask	0 = 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.7		Reserved - set to zero	Reserved - set to zero

CFG_WA Answer

ID	Parameters
CFG_WA=0x85	None

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.

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.

WIF_WR Request

ID	Parameters
WIF_WR=0x06	194 bytes

Parameters

Byte offset	Format	Name	Description
0	Int8[33] null terminated string	WLAN_SSID	WLAN SSID maximum 32 characters + null termination. Null terminate unused chars.
33	Int8[64] null terminated string	WLAN_KEY	SSID Key maximum 63 characters + null termination. Null terminate unused chars.
97	Byte[97]	AUTH_TOKEN	API authentication token for Astrocast backend via Wi-Fi module. Fixed size 96 bytes + null termination.

WIF_WA Answer

ID	Parameters
WIF_WA=0x86	None

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

ID	Parameters
SSC_WR=0x07	2 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	Search Period Enumeration	See table below. Default 0
1.0	Bit	Enable search without message queued	1 = search without message queued. 0 (default) = only search when a message is queued
1.1-1.7		Reserved

Search Period Enumeration	Time (milliseconds)
0	17'905 (default)
1	1'377
2	2'755
3	4'132
4	15'150
5	17'905
6	23'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

ID	Parameters
SSC_WA=0x87	None

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

ID	Parameters
CFG_SR=0x10	None

CFG_SA Answer

ID	Parameters
CFG_SA=0x90	None

CFG_F Factory Reset

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

CFG_FR Request

ID	Parameters
CFG_FR=0x11	None

CFG_FA Answer

ID	Parameters
CFG_FA=0x91	None

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

ID	Parameters
CFG_RR=0x15	None

CFG_RA Answer

ID	Parameters
CFG_RA=0x95	8 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	Product ID	0-2: Reserved 3: Commercial Satellite Astronode 4: Commercial Wi-Fi Dev Kit
1	UInt8	Hardware revision	Module electronics version
2	UInt8	Firmware major version	Used when there is a loss of compatibility with previous versions
3	UInt8	Firmware minor version	Used when features are added in a backwards compatible manner
4	UInt8	Firmware revision	Used when fixing bugs in a backwards compatible manner
5.0	Bit	Payload Acknowledgement	0 = Asset not informed of payload acks 1 = Asset is informed of payload acks (default) Note: Least Significant bit (LSb) is right most
5.1	Bit	Add Geolocation	0 = No Geolocation (default) 1 = Add Geolocation
5.2	Bit	Ephemeris Enabled	0 = Ephemeris disabled 1 = Ephemeris enabled (default)
5.3	Bit	Deep Sleep Mode Enabled	0 = Deep sleep mode not used (default) 1 = Deep sleep mode is used
5.4-5.7		Reserved	Reserved
6.0-6.7		Reserved	Reserved
7.0	Bit	Payload Ack Event Pin Mask enabled	0 = EVT pin does not show EVT register Payload Ack bit state 1 = EVT pin shows EVT register Payload Ack bit state (default)
7.1	Bit	Reset Notification Event Pin Mask enabled	0 = 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.2	Bit	Command Available Event Pin Mask enabled	0 = EVT pin does not show EVT register Command Available bit state 1 = EVT pin shows EVT register Command Available bit state (default)
7.3	Bit	Message Transmission (Tx) Pending Event Pin Mask enabled	0 = 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.7		Reserved	Reserved

Module Information

RTC_R RTC Read

Reads the module’s real time clock information.

RTC_RR Request

ID	Parameters
RTC_RR=0x17	None

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.

ID	Parameters
RTC_RA=0x97	4 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt32	RTC time	Time 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

ID	Parameters
NCO_RR=0x18	None

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.

ID	Parameters
NCO_RA=0x98	4 byte

Parameters

Byte offset	Format	Name	Description
0	UInt32	Time to next pass	Time 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

ID	Parameters
MGI_RR=0x19	None

MGI_RA Answer

ID	Parameters
MGI_RA=0x99	36 bytes

Parameters

Byte offset	Format	Name	Description
0	Int8[36]	GUID	GUID 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

ID	Parameters
MSN_RR=0x1A	None

MSN_RA Answer

ID	Parameters
MSN_RA=0x9A	16 bytes

Parameters

Byte offset	Format	Name	Description
0	Int8[16]	Serial Number	Serial 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

ID	Parameters
MPN_RR=0x1B	None

MPN_RA Answer

ID	Parameters
MPN_RA=0x9B	16 bytes

Parameters

Byte offset	Format	Name	Description
0	Int8[16]	Product Number	Product Number, with unused characters null terminated (\0)

Message Management

PLD_E Enqueue Payload

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.

caution

Although the module normally replies within 100ms, under certain exceptional conditions it could take up to 1.2 seconds.

PLD_ER Request

ID	Parameters
PLD_ER=0x25	N + 2 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt16	Payload ID	An identifier for the payload, chosen by the asset. It cannot match an existing Payload ID present in the module queue.
2	Byte [N]	Payload Data	The 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

ID	Parameters
PLD_ER=0xA5	Payload ID

Parameters

Byte offset	Format	Name	Description
0	UInt16	Payload ID	The Payload ID specified by the Asset in the PLD_ER.

PLD_D Dequeue Payload

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

PLD_DR Request

ID	Parameters
PLD_DR=0x26	None

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:

ID	Parameters
PLD_DA=0xA6	2 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt16	Payload ID	The ID of the payload removed from the module queue.

PLD_F Clear/Free Payloads

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

PLD_FR Request

ID	Parameters
PLD_FR=0x27	None

info

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

PLD_FA Answer

ID	Parameters
PLD_FA=0xA7	None

GEO_W Geolocation Write

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.

GEO_WR Request

ID	Parameters
GEO_WR=0x35	8 bytes

Parameters

Byte offset	Format	Name	Description
0	Int32	Latitude	Degrees Latitude * 1E7 (i.e., latitude multiplied by 10'000'000) Must be in the range -90° to 90°
4	Int32	Longitude	Degrees 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

ID	Parameters
GEO_WA=0xB5	None

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

ID	Parameters
EVT_RR=0x65	None

EVT_RA Answer

ID	Parameters
EVT_RA=0xE5	1 byte

Parameters

Byte offset	Format	Name	Description
0.0	Bit	Satellite Ack Available	A satellite payload acknowledgement is available to be read and confirmed
0.1	Bit	Module Reset	Module has reset
0.2	Bit	Command Available	A command is available to be read and confirmed
0.3	Bit	Message Transmit Pending	An uplink message is present in the message queue, waiting to be sent, and module power should not be cut.
0.4-7		Reserved

SAK_R Read Satellite ACK

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

SAK_RR Request

ID	Parameters
SAK_RR=0x45	None

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.

ID	Parameters
SAK_RA=0xC5	2 bytes

Parameters

Byte offset	Format	Name	Description
0	UInt16	Payload ID	Identifier 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

ID	Parameters
SAK_CR=0x46	None

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

ID	Parameters
SAK_CA=0xC6	None

Command Management

CMD_R Command Read

Since firmware version 2.8.0

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

CMD_RR Request

ID	Parameters
CMD_RR=0x47	None

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.

ID	Parameters
CMD_RA=0xC7	4 + N bytes

Parameters

Byte offset	Format	Name	Description
0	UInt32	Created Date	In seconds since 2018-01-01 00:00:00 UTC
4	UInt8[N]	Payload	N 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

ID	Parameters
CMD_CR=0x48	None

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

ID	Parameters
CMD_CA=0xC8	None

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

ID	Parameters
VAL_WR=0x60	None

VAL_WA Answer

ID	Parameters
VAL_WA=0xE0	None

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.

info

Validation mode must be enabled to use this command.

caution

After 10 test transmissions this request will return an error.

TTX_SR Request

ID	Parameters
TTX_SR=0x61	1 Byte

Parameters

Byte offset	Format	Name	Description
0	Byte	Tx time (sec)	Start a test transmission for up to 30 seconds

TTX_SA Answer

ID	Parameters
TTX_SA=0xE1	1 Byte

Parameters

Byte offset	Format	Name	Description
0	Byte	Transmissions remaining	Number 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

ID	Parameters
GPO_SR=0x62	2 Bytes

Parameters

Byte offset	Format	Name	Description
0	Byte	Pin ID	0 = EVENT_NOTIF, 1 = ANTN_USE
1	Byte	State	0 = OFF, 1 = ON

GPO_SA Answer

ID	Parameters
GPO_SA=0xE2	0 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

ID	Parameters
GPI_RR=0x63	1 Byte

Parameters

Byte offset	Format	Name	Description
0	Byte	Pin ID	2 = WAKEUP

GPI_RA Answer

ID	Parameters
GPI_RA=0xE3	1 Byte

Parameters

Byte offset	Format	Name	Description
0	Byte	State	0 = 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

ID	Parameters
ADC_RR=0x64	0 Byte

ADC_RA Answer

ID	Parameters
ADC_RA=0xE4	4 Bytes

Parameters

Byte offset	Format	Name	Description
0	Uint32	Analog Voltage	3.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

ID	Parameters
RES_CR=0x55	None

RES_CA Answer

ID	Parameters
RES_CA=0xD5	None

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

ID	Parameters
CTX_SR=0x66	None

CTX_SA Answer

The answer confirms that the counters have been saved.

ID	Parameters
CTX_SA=0xE6	None

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

ID	Parameters
PER_RR=0x67	None

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.

ID	Parameters
PER_RA=0xE7	N bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	1st Performance Counter Type (T)	Describes the type - see below
1	UInt8	Length of the 1st counter (L)	Number of bytes
2	L Byte Value	Value of the 1st counter (V)	Value. If Length > 1: little endian format
3 + (Lprev)	...	TLV value scheme repeats

Counter Type	Expected Length	Data Type	Value	Description
0x01	4	UInt32	Satellite search phase count	How many times the module has entered the satellite search phase. This may consist of multiple satellite detection operations
0x02	4	UInt32	Satellite detection operation count	Each satellite search phase may contain multiple satellite detection operations, as multiple frequencies are checked
0x03	4	UInt32	Signalling demodulation phase count	How many times the module has entered the signalling demodulation phase with a detected satellite. This may consist of multiple signalling demodulation attempts
0x04	4	UInt32	Signalling demodulation attempt count	How many signalling demodulations have been attempted
0x05	4	UInt32	Signalling demodulation success count	How many signalling demodulations have succeeded
0x06	4	UInt32	Acknowledgement demodulation attempt count	How many ack demodulations have been attempted
0x07	4	UInt32	Acknowledgement demodulation success count	How many ack demodulations have succeeded
0x08	4	UInt32	Queued message count	The number of messages that have been queued
0x09	4	UInt32	Dequeued unacked message count	Count of un-acknowledged messages dequeued. Dequeuing or freeing acked messages will not increment this count.
0x0A	4	UInt32	Acknowledged message count	The number of messages that have been ack'ed by satellites
0x0B	4	UInt32	Sent fragment count	The number of fragments that have been sent to satellites
0x0C	4	UInt32	Acknowledged fragment count	The number of fragments that have been ack'ed by satellites
0x0D	4	UInt32	Command demodulation attempt count	How many command demodulations have been attempted
0x0E	4	UInt32	Command demodulation success count	How 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

ID	Parameters
PER_CR=0x68	None

PER_CA Answer

The answer confirms that the counters have been zeroed.

ID	Parameters
PER_CA=0xE8	None

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

ID	Parameters
MST_RR=0x69	None

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.

ID	Parameters
MST_RA=0xE9	N bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	1st Module State Detail Type (T)	Describes the type - see below
1	UInt8	Length of the 1st detail (L)	Number of bytes
2	L Byte Value	Value of the 1st detail (V)	Value. If Length > 1: little endian format
3 + (Lprev)	...	TLV value scheme repeats

Module State Details Type	Expected Length	Data Type	Value	Description
0x41	1	UInt8	Messages in queue	Includes ack'ed messages waiting to be read/confirmed
0x42	1	UInt8	Ack'ed messages in queue	Messages that have been ack'ed by satellites
0x43	1	UInt8	Last reset reason	See the table below for reasons
0x44	4	UInt32	Uptime	Number 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 Type	Reset Reason	Description
0x00	No reset	No reset has been detected
0x01	General reset	Power was applied and the module started up; or rising edge on the reset pin; or wake up from deep-sleep
0x02	Software reset	Module software intentionally reset
0x03	Watchdog reset	Module software unintentionally reset
0x04	Brown out	Module 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

ID	Parameters
LCD_RR=0x6A	None

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.

ID	Parameters
LCD_RA=0xEA	N bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	1st Last Contact Detail Type (T)	Describes the data type - see below
1	UInt8	Length of the 1st detail (L)	Number of bytes
2	L Byte Value	Value of the 1st detail (V)	Value. If Length > 1: little endian format
3 + (Lprev)	...	TLV value scheme repeats

LCD Type ID	Expected Length	Data Type	Value	Description
0x51	4	UInt32	Time 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
0x52	4	UInt32	Time 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
0x53	1	UInt8	Peak RSSI of last pass	Expected range 0-30 for most environments
0x54	4	UInt32	Time 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

ID	Parameters
END_RR=0x6B	None

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.

ID	Parameters
END_RA=0xEB	N bytes

Parameters

Byte offset	Format	Name	Description
0	UInt8	1st Environment Detail Type (T)	Describes the data type - see below
1	UInt8	Length of the 1st detail (L)	Number of bytes
2	L Byte Value	Value of the 1st detail (V)	Value. If Length > 1: little endian format
3 + (Lprev)	...	TLV value scheme repeats

Env Detail Type ID	Expected Length	Data Type	Value	Description
0x61	1	UInt8	Last MAC Result	Values are described in the table below.
0x62	1	UInt8	Last satellite search peak RSSI	The maximum RSSI seen in the last search. If multiple channels are checked, it is the maximum value. Expected range 0-30 for most environments
0x63	4	UInt32	Time since last satellite search (sec)	This is a relative time (seconds since) because the absolute time may not be known by the module

MAC Result	Description
0	None
1	Success
2	Satellite not detected
3	Sync demodulation fail
4	Signalling demodulation fail
5	Ack signalling fail
6	No ack in frame
7	Error
8	Timeout
9	Blacklisted
10	Test Satellite
11	Satellite 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

ID	Parameters
HTX_SR=0x6C	1 Byte

Parameters

Byte offset	Format	Name	Description
0	UInt16	Tx time (sec)	Transmit for this amount of time
2	UInt8	Freq Enumeration	Select the L-band Tx frequency as low, middle, or high
3.0	Bit	Modulation	0 = unmodulated (carrier wave); 1 = modulated
3.1-3.7		Reserved	Set to zero

Freq Enumeration	Frequency Selected
0	Low
1	Middle
2	High

HTX_SA Answer

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

ID	Parameters
HTX_SA=0xEC	Empty

Errors

The structure of an error answer is defined here:

ID	Parameters
ERROR=0xFF	UInt16 Error Code

Parameters

Byte offset	Format	Name	Description
0	UInt16	Error Code	See the list of error code in Table 3

Table 3 - Error code list

Error code	Error type	Name	Description
0x0001	COMM	CRC_NOT_VALID	Discrepancy between provided CRC and expected CRC.
0x0011	COMM	LENGTH_NOT_VALID	Message length is not valid for the operation code, or the message exceeds the maximum length for a frame.
0x0121	COMM	OPCODE_NOT_VALID	Invalid Operation Code used.
0x0122	COMM	ARG_NOT_VALID	Invalid argument used.
0x0123	COMM	FLASH_WRITING_FAILED	Failed to write to the flash.
0x0124	COMM	DEVICE_BUSY	Device is busy.
0x0601	WIF_ER	FORMAT_NOT_VALID	At least one of the fields (SSID, password, token) is not composed of exclusively printable standard ASCII characters (0x20 to 0x7E).
0x0701	SSC_ER	PERIOD_INVALID	The Satellite Search Config period enumeration value is not valid
0x2501	PLD_ER	BUFFER_FULL	Failed to queue the payload because the sending queue is already full.
0x2511	PLD_ER	DUPLICATE_ID	Failed to queue the payload because the Payload ID provided by the asset is already in use in the module queue.
0x2601	PLD_DR	BUFFER_EMPTY	Failed to dequeue a payload from the buffer because the buffer is empty
0x3501	GEO_WR	INVALID_POS	Failed to update the geolocation information. Latitude and longitude fields must in the range [-90,90] degrees and [-180,180] degrees, respectively.
0x4501	SAK_RR	NO_ACK	No satellite acknowledgement available for any payload.
0x4601	SAK_CR	NO_ACK_CLEAR	No payload ack to clear, or it was already cleared.
0x4701	CMD_RR	NO_COMMAND	No command is available.
0x4801	CMD_CR	NO_COMMAND_CLEAR	No command to clear, or it was already cleared.
0x6101	TTX_SR	MAX_TX_REACHED	Failed to test Tx due to the maximum number of transmissions being reached.