adafruit_rockblock

CircuitPython driver for Rock Seven RockBLOCK Iridium satellite modem

  • Author(s): Carter Nelson

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_rockblock.RockBlock(uart, baudrate=19200)

Driver for RockBLOCK Iridium satellite modem.

data_in

The binary data in the inbound buffer.

data_out

The binary data in the outbound buffer.

energy_monitor

The current accumulated energy usage estimate in microamp hours.

Returns an estimate of the charge taken from the +5V supply to the modem, in microamp hours (uAh). This is represented internally as a 26-bit unsigned number, so in principle will rollover to zero after approx. 67Ah (in practice this is usually greater than battery life, if battery-powered).

The accumulator value is set to zero on a power-cycle or on a watchdog reset. Note that while +5V power is supplied to the Data Module but the module is powered off by its ON/OFF control line, it will still be consuming up to a few tens of microamps, and this current drain will not be estimated in the +GEMON report.

The setter will preset the energy monitor accumulator to value n (typically, <n> would be specified as 0, to clear the accumulator).

Note: Call Processor/BOOT Version: TA16005 is known to not support the AT+GEMON energy monitor command. It is however known to work on TA19002 (newer) and TA12003 (older). You may use the revision function to determine which version you have. Function will return None if modem cannot retrieve the accumulated energy usage estimate.

Returns int

geolocation

Most recent geolocation of the modem as measured by the Iridium constellation including a timestamp of when geolocation measurement was made.

The response is in the form: (<x>, <y>, <z>, <timestamp>)

<x>, <y>, <z> is a geolocation grid code from an earth centered Cartesian coordinate system, using dimensions, x, y, and z, to specify location. The coordinate system is aligned such that the z-axis is aligned with the north and south poles, leaving the x-axis and y-axis to lie in the plane containing the equator. The axes are aligned such that at 0 degrees latitude and 0 degrees longitude, both y and z are zero and x is positive (x = +6376, representing the nominal earth radius in kilometres). Each dimension of the geolocation grid code is displayed in decimal form using units of kilometres. Each dimension of the geolocation grid code has a minimum value of –6376, a maximum value of +6376, and a resolution of 4. This geolocation coordinate system is known as ECEF (acronym earth-centered, earth-fixed), also known as ECR (initialism for earth-centered rotational)

<timestamp> is a time_struct The timestamp is assigned by the modem when the geolocation grid code received from the network is stored to the modem’s internal memory.

The timestamp used by the modem is Iridium system time, which is a running count of 90 millisecond intervals, since Sunday May 11, 2014, at 14:23:55 UTC (the most recent Iridium epoch). The timestamp returned by the modem is a 32-bit integer displayed in hexadecimal form. We convert the modem’s timestamp and return it as a time_struct.

The system time value is always expressed in UTC time.

Returns a tuple: (int, int, int, time_struct)

model

Return modem model.

reset()

Perform a software reset.

revision

Modem’s internal component firmware revisions.

For example: Call Processor Version, Modem DSP Version, DBB Version (ASIC), RFA VersionSRFA2), NVM Version, Hardware Version, BOOT Version

Returns a tuple: (string, string, string, string, string, string, string)

ring_alert

The current ring indication mode.

False means Ring Alerts are disabled, and True means Ring Alerts are enabled.

When SBD ring indication is enabled, the ISU asserts the RI line and issues the unsolicited result code SBDRING when an SBD ring alert is received. (Note: the network can only send ring alerts to the ISU after it has registered).

Returns: bool

ring_indication

The ring indication status.

Returns the reason for the most recent assertion of the Ring Indicate signal.

The response contains separate indications for telephony and SBD ring indications. The response is in the form: (<tel_ri>,<sbd_ri>)

<tel_ri> indicates the telephony ring indication status: 0 No telephony ring alert received. 1 Incoming voice call. 2 Incoming data call. 3 Incoming fax call.

<sbd_ri> indicates the SBD ring indication status: 0 No SBD ring alert received. 1 SBD ring alert received.

Returns a tuple: (string, string)

satellite_transfer(location=None)

Initiate a Short Burst Data transfer with satellites.

serial_number

Modem’s serial number, also known as the modem’s IMEI.

Returns string

signal_quality

Signal Quality also known as the Received Signal Strength Indicator (RSSI).

Values returned are 0 to 5, where 0 is no signal (0 bars) and 5 is strong signal (5 bars).

Important note: signal strength may not be fully accurate, so waiting for high signal strength prior to sending a message isn’t always recommended. For details see https://docs.rockblock.rock7.com/docs/checking-the-signal-strength

Returns: int

status

Return tuple of Short Burst Data status.

system_time

Current date and time as given by the Iridium network.

The system time is available and valid only after the ISU has registered with the network and has received the Iridium system time from the network. Once the time is received, the ISU uses its internal clock to increment the counter. In addition, at least every 8 hours, or on location update or other event that requires re-registration, the ISU will obtain a new system time from the network.

The timestamp used by the modem is Iridium system time, which is a running count of 90 millisecond intervals, since Sunday May 11, 2014, at 14:23:55 UTC (the most recent Iridium epoch). The timestamp returned by the modem is a 32-bit integer displayed in hexadecimal form. We convert the modem’s timestamp and return it as a time_struct.

The system time value is always expressed in UTC time.

Returns: time_struct

text_in

The text in the inbound buffer.

text_out

The text in the outbound buffer.