Lua Functions

These options can be sent to the terminal via the "Send Command" function within the tracking platform, entered through the RS232 serial connection, or the USB cable via CDC mode.

Our implementation is built around Lua, the Lua 5.1 series reference manual, and reference manual and most language features are enabled except for math and OS libraries. Because the Lua interpreter is built in integer-only mode, it is not possible to use floating-point numbers or their specific representations (such as 1e3 instead of 1000).

GPS functions

// GPS Power
gps.setpower({mode})
// NOTE: Iridium modem must be powered on for GPS to get signal
// mode: 1 for on and initialize, 0 for off

// Get GPS Time
{second}, {minute}, {hour}, {day}, {month}, {year} = gps.gettime()
{epochseconds} = gps.getunixtime()

// Get Position
{latitude}, {longitude}, {speed}, {altitude}, {course}, {hdop} = gps.getpos()

Messaging functions

// Encode position report in format set by settings.settings_format
{string} = gsattrack.encposition({latitude}, {longitude}, {speed}, {course}, {battery percent}, {altitude}, {epochseconds})

// Encode email/text message
{string} = gsattrack.enctext({destination}, {message})

// Encode settings report
{string} = gsattrack.encsettings()

Caching functions

// Store a message for Iridium transmission (MO) or local deliver (MT) cache.cache( {termination}, {cache_message} )

termination: cache.MO: (term=0) mobile originated, will be sent during next iridium transmit cycle cache.MT: (term=1) mobile terminated

// Clear a message from the cache cache.clearcache( { termination }, { id } )

Example: destination = [[test@test.com]] text_message = [[This is a test message]] cache.cache(cache.MO,gsattrack.enctext( destination, text_message ))

This will be acknowledged with a message similar to the following: C#T#SC#id:01,term:0,l:37,e:0

This message will be sent on the next schedule transmit cycle.

A transmit cycle can be triggered with the following: pmu.pm9(1)

Incoming or stored MT messages will be printed at the console repeatedly if the message begins with an ASCII printable character as well as a hexadecimal representation of the message:

C#T#GC#id:00,term:1,msg:This is a test message C#T#GC#id:00,term:1,msg:0x5468697320697320612074657374206d657373616765
 
C#T#GC#id:00,term:1,msg:This is a test message C#T#GC#id:00,term:1,msg:0x5468697320697320612074657374206d657373616765

This message can be acknowledged and cleared using this command: cache.clearcache( cache.MT, 0 )

This will be acknowledged with a: C#T#CC#id:00,term:1

If additional messages were in the queue, the next id message would be displayed repeatedly until all have been cleared.

Iridium functions

// Power Iridium Modem
iridium.setpower({mode})
-- mode: 1 for on, 0 for off
-- NOTE: Must be called with mode 1 to enable signal for GPS functionality

// Enable Iridium Radio
iridium.setradio({mode})
-- mode: 1 for on, 0 for off

iridium.transmit({string})
-- string: arbitrary string to transmit over SBD
-- Example:

message, message_hour = gsattrack.encposition(lat, lon, speed, course, batp, min, alt, epochseconds)
-- send recent position (less than one hour old)
iridium.transmit(message)

-- send position with hour (for messages sent more than an hour after the position time)
iridium.transmit(message .. message_hour)

-- get Iridium IMEI
serial = iridium.getserial()
-- or to print the current serial number:
print("IMEI: " .. iridium.getserial())

-- get the current signal level (0 = no signal, 5 = full signal)
signal = iridium.getsignal()
-- or print the current signal level
print("Signal: " .. iridium.getsignal() .. "/5")

GPIO functions

{ variable } = gpio.wakereason()
-- Values:
-- gpio.UNKNOWN: no matching wake reason
-- gpio.POWERUP: unit was just powered on
-- gpio.RESETPIN: unit was reset using the reset button
-- gpio.WAKEPIN: unit was woken using the wake pin
-- gpio.RTC: unit was woken by RTC
-- gpio.POWERCONNECTED: unit was woken when power was connected

Compass functions

// Compass heading in degrees
{ variable } = compass.getheading()

// Monitor compass and accelerometer values
{ variable } = compass.setmonitor({mode})
// mode: 1 for on, 0 for off
// Example output: A#hd:208,mx:-142,my:-79,mz:-100,ax:-96,ay:16,az:16784
// A#hd:<heading>,mx:<mag. field x>,my:<mag. field y>,mz:<mag. field z>,ax:<accel x>,ay:<accel y>,az:<accel z>

Accelerometer functions

// Temperature in degrees Celsius
{ variable } = accel.gettemp()

// Unit orientation
{ variable } = accel.getorientation()
// Values to compare with:
// accel.UP_SX (0x44): Y-low
// accel.UP_DX (0x42): X-high
// accel.DW_SX (0x41): X-low
// accel.DW_DX (0x48): Y-high
// accel.TOP (0x60): Z-high
// accel.BOTTOM (0x50): Z-low
// accel.NA (0x00): ??

Battery functions

// Battery percentage (integer value from 0 to 100)
print(bat.getpercent())

// Battery voltage in millivolts (e.g., 4000 = 4.0V)
print(bat.getvoltage())

// Enable/disable periodic battery state logging
bat.setmonitor({mode})
// mode: 1 for on, 0 for off

// Example output (Current):
// B#S#pct:98.19,v:4.195,tmp:25,pct_h:3,pwr:1
// B#S#pct:<bat percent>,v:<battery voltage in volts>,tmp:<temp in celsius>,pct_h:<battery pct change/hr>,pwr:<1=external power,0=no ext. power>

// Example output (Legacy):
// B#S#bp:9819,mv:4195,tmp:25,pct_h:3,pwr:1
// B#S#bp:<bat percent * 100>,mv:<battery voltage in mv>,tmp:<temp in celsius>,pct_h:<battery pct change/hr>,pwr:<1=external power,0=no ext. power>

Settings functions

These settings can be configured through the "Send Command" function on the tracking platform site (found under the down arrow menu for the GSatMicro asset of interest). The "Get Parameters" function on this screen can request the current parameters stored on the device. Sending parameter requests through the site to the unit will not automatically update fields on the site. "Get Parameters" can be used to confirm the current configuration state of the unit.

//Set variable into flash settings.flash( {setting}, {value} )

//Read variable from flash {variable} = settings.flash( {setting} )

setting: settings.sleep // Seconds to sleep when in NORMAL mode (between cycles) (range: 1 - ( 2^31 - 1 ) ) settings.sos_sleep //Seconds to sleep when in Alert mode (between cycles) (range: 1 - ( 2^31 - 1 ) ) settings.g_timeout //GPS Timeout in seconds, default 120 (range: 1 - ( 2^31 - 1 ) ) settings.g_hdop //GPS Horizontal Dilution of Precision needed x10, default 20 (range 10 - 500) settings.g_settle // Seconds to settle GPS after getting a fix, default 15 (range: 1 - ( 2^31 - 1 ) ) settings.i_tx_timeout //Iridium transmit timeout, default 60 (range: 1 - ( 2^31 - 1 ) ) settings.i_signal_timeout //Iridium signal timeout, default 60 (range: 1 - ( 2^31 - 1 ) ) settings.i_tx_retries //Iridium transmit attempts, default 3 (range: 0 - ( 2^31 - 1 ) ) settings.sleep_w_power // Set to 1 to sleep when on external high voltage // (does not sleep on USB), default 0 (range: 0=sleep,1=run, count down to next cycle) settings.led_mask // mask to mask off LED's, default 0xFF (range: 0 - 255, 0=all off, 255=all on) Membrane Panel Individual Bits: bit0: GPS bit1: Message bit2: Power bit3: Satellite bit4: Alarm bit5-7: ignored

settings.tx_altitude // transmit altitude with position reports, default 1 (range: 0=off,1=on) settings.low_bat_off // on: go into permanent storage mode when battery runs down, // off: go into temporary storage mode on low battery, restore transmitting on power // default 0 (range: 0=off,1=on)

**Version 2 or Later:**

settings.g_hibernate_sleep // on: hibernate GPS for faster initialization from sleep (consumes more power during sleep) // off: turn GPS off during sleep // default 0 (range: 0=off,1=on)

settings.cache_reports // on: cache up to 30 position reports when GPS is available but Iridium is not // off: no caching, failed position report transmissions are discarded // default 0 (range: 0=off,1=on)

**Version 3 or Later:**

settings.i_rx_always // keeps radio awake always to receive commands, default 0 (range: 0=off,1=on) (present in earlier versions, functional version>=3) settings.moving_sleep // Seconds to sleep when in MOVING mode (between cycles) (range: 1 - ( 2^31 - 1 ) ) settings.moving_thresh // Meters/second threshold for switching to MOVING mode, only triggered while GPS is active 0=disabled (range: 0 - ( 2^31 - 1 ) ) settings.require_encrypted_mt // on: discard all mobile terminated messages that are not encrypted // off: accept encrypted/non-encrypted mobile terminated messages // default 0 (range: 0=off,1=on)

settings.g_on_always // on: GPS remains active and tracking after acquiring position // (useful in conjunction with moving_sleep/moving_thresh for externally powered units to trigger moving mode at any time) // off: GPS powers off or hibernates after acquiring position // default 0 (range: 0=off,1=on)

**Version 4 or Later:**

settings.sleep_w_bat // on: enter low power sleep while on battery power until triggered to wake or next report interval // off: remain in higher power running mode at all times // default 1 (range: 0=off,1=on)

**Version 5 or Later:**

settings.tx_seconds // transmit seconds with position reports(default reports are 2 minute resolution), default 0 (range: 0=off,1=on)

**Version 6 or Later:**

settings.report_format // which report format to use for transmission, default 0 // (range: 0=proprietary small GSE packet, // 1=public 10 byte packet format, // 2=public 18 byte high resolution packet format)

**Version 7 or Later:**

settings.extpwr_sleep // seconds to sleep when on external power (between cycles), default 0=disabled (range: 0 - ( 2^31 - 1 ) ) settings.extpwr_autostart // whether to wakeup from sleep mode when external power is applied, default 0 (range: 0=off, 1=on)

**Version 8 or Later:**

settings.nmea // whether to output NMEA on RS232. when enabled, NMEA console output is disabled. default 0 (range: 0=off, 1=on)

**Version 9 or Later:**

settings.ble_off // whether to turn BLE off, default 0 (range: 0=BLE on, 1=BLE off)

**Version 10 or Later:**

settings.accel_thresh // threshold to wakeup from sleep upon accelerometer movement, default 0=disabled, (range: 0-127, lower values are higher sensitivity )

Example: //Set sleep time between reports to 10 minutes settings.flash(settings.sleep, 600)

//Print current sleep time print(settings.flash(settings.sleep))

// List all current settings: settings.listflash() output: S#P#defaultv:2 S#P#g_hdop:20 S#P#g_timeout:300 S#P#i_tx_timeout:60 S#P#i_signal_timeout:60 S#P#i_tx_retries:3 S#P#sleep:120 S#P#sos_sleep:30 S#P#sleep_w_power:0 S#P#led_mask:255 S#P#i_rx_always:0 S#P#tx_altitude:1 S#P#g_settle:15 S#P#t_adc_id:0 S#P#t_adc_threshold:0 S#P#status_line:0 S#P#low_bat_off:0

//Set LEDled.led( {led}, {led mode}, {cycles} )// Set LED with cycles set to continuousled.led( {led}, {led mode} )//Read current LED mode{variable} = led.led( {led} )led:led.pwr: Powerled.gps: GPSled.sat: Satellite/Iridiumled.alrm: Alarmled.msg: Messageled mode:led.off: offled.on: on (solid)led.fadeoff: fade from bright to darkled.fadeon: fade from dark to lightled.slow: slow flashled.medium: medium flashled.fast: fast flashled.1: single flashled.2: two flashesled.3: three flashesled.4: four flashesled.5: five flashescycles:The number of times to repeat the mode sequence. 255 = forever.Example://Set LED 0 to ON permanentlyled.led(led.pwr, led.on, 255)

Interrupts / Event Handlers

A set of Lua functions can be defined for servicing various state changes on the GSatMicro.

cpu.set_int_handler({interrupt type}, {function})
// interrupt type:
// cpu.INT_IRIDIUM_SIGNAL: Iridium modem has a signal from the satellite network
// cpu.INT_IRIDIUM_TX_OK: SBD transmit completed successfully
// cpu.INT_IRIDIUM_TX_FAIL: SBD transmission failed (after settings.i_tx_retries retries)
// cpu.INT_IRIDIUM_TIMEOUT: Iridium timeout waiting for a signal from the satellite network
// cpu.INT_GPS_VALID: GPS fix is valid and settled
// cpu.INT_GPS_TIMEOUT: Timeout waiting for GPS fix
// cpu.INT_BOOT: Called at boot
// cpu.INT_CONTENTION: Iridium modem is already receiving when a radio command was issued

// Example:
function iridium_signal()
    lat, lon, speed, alt, course = gps.getpos()
    sec, min = gps.gettime()
    epochseconds = gps.getunixtime()
    if (speed < 5) then
        course = compass.heading()
    end
    batp = bat.percent()
    message, message_hour = gsattrack.encposition(lat, lon, speed, course, batp, min, alt, epochseconds)
end

cpu.set_int_handler(cpu.INT_IRIDIUM_SIGNAL, iridium_signal)

Log functions

The amount of logging displayed on the serial output can be configured.

log.setlevel({level})level:-1 = None 0 = Info 1 = Debug

Licenses/Credits

eLua and Lua core components are available under the MIT license. Additional components and licenses for the project are described here

Additional 3rd Party Software/Credits:

trigint: /*

   Copyright (c) 2010 Dave Dribin

   Permission is hereby granted, free of charge, to any person
   obtaining a copy of this software and associated documentation
   files (the "Software"), to deal in the Software without
   restriction, including without limitation the rights to use, copy,
   modify, merge, publish, distribute, sublicense, and/or sell copies
   of the Software, and to permit persons to whom the Software is
   furnished to do so, subject to the following conditions:

   The above copyright notice and this permission notice shall be
   included in all copies or substantial portions of the Software.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
   BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
   ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
   SOFTWARE. */

isqrt:

This product uses code for isqrt (integer square root) written by John Halleck, which is being used by his permission.

/ _Integer square root by Halleck's method, with Legalize's speedup_ / / (http://www.cc.utah.edu/~nahaj/factoring/isqrt.legalize.c.html)_ /

sha1: /* This code is public-domain - it is based on libcrypt

  placed in the public domain by Wei Dai and other contributors. */

sha2: /*

   FILE: sha2.c
   AUTHOR: Aaron D. Gifford -  (http://www.aarongifford.com/)

   Copyright (c) 2000-2001, Aaron D. Gifford
   All rights reserved.

-   Redistribution and use in source and binary forms, with or without
-   modification, are permitted provided that the following conditions
   are met:
   1.  Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 2.  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
   3.  Neither the name of the copyright holder nor the names of contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.
   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTOR(S) ``AS IS'' AND
   ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTOR(S) BE LIABLE
   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   SUCH DAMAGE.

	
   Copyright (c) 2008 Damien Bergamini  [damien.bergamini@free.fr]
    

   Permission to use, copy, modify, and distribute this software for any
    
   purpose with or without fee is hereby granted, provided that the above
    
   copyright notice and this permission notice appear in all copies.
    

   THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    
   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    
   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    
   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    
   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    
   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    
   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
    
   hmac: Based on RFC2104 example source code for hmac_md5 by Krawczyk, et. al.
    
   unity: / _========================================== Unity Project - A Test Framework for C Copyright (c) 2007 Mike Karlesky, Mark VanderVoord, Greg Williams  [Released under MIT License. Please refer to license.txt for details]  ==========================================_ /