ClearWatch 250

state(7) = dfuMANIFEST, status(0) = No error condition is present
state(8) = dfuMANIFEST-WAIT-RESET, status(0) = No error condition is present
Done!

state(7) = dfuMANIFEST, status(0) = No error condition is present
state(8) = dfuMANIFEST-WAIT-RESET, status(0) = No error condition is present
Done!

// GPS Power
gps.setpower( {mode} )
NOTE: Iridium modem must be powered on for GPS to get signal

mode:
1: on and initialize
0: 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()

// 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()

// 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)

NOTE: Ensure that each line of an entered command does not exceed 128 characters.
Lua string construction can be split across lines in the following manner:

text_message = [[This is a really ]] ..
[[long message]]

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.

// Power Iridium Modem
iridium.setpower( {mode} )

mode:
1: on
0: off

NOTE: Must be called with mode 1 to enable signal for GPS functionality

// Enable Iridium Radio
iridium.setradio( {mode} )

mode:
1: on
0: 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 current serial number:
print("IMEI: " .. iridium.getserial())

-- get current signal level (0 = no signal, 5 = full signal)
signal = iridium.getsignal()

-- or print the current signal level
print("Signal: " .. iridium.getsignal() .. "/5")

{ 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 heading in degrees
{ variable } = compass.getheading()

// Monitor compass and accelerometer values
{ variable } = compass.setmonitor( {mode} )

mode:
1: on
0: 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>

// 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 percentage integer value from 0 to 100
print(bat.getpercent())

//Battery voltage in millivolts IE: 4000 = 4.0V
print(bat.getvoltage())

// Enable/disable periodic battery state logging
bat.setmonitor( {mode} )

mode:
1: on
0: 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>

These settings can be configured through the "Send Command" function on the tracking platform site
(found under the down arrow menu for the ClearWatch 250 asset of interest). The "Get Parameters" function
from 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.

NOTE: All numbers entered into the device must be integer values.

//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

NOTE: These functions are currently overridden during normal transmit behavior by built-in functions.  

//Set LED
led.led( {led}, {led mode}, {cycles} )

// Set LED with cycles set to continuous
led.led( {led}, {led mode} )

//Read current LED mode
{variable} = led.led( {led} )

led:
led.pwr: Power
led.gps: GPS
led.sat: Satellite/Iridium
led.alrm: Alarm
led.msg: Message

led mode:
led.off: off
led.on: on (solid)
led.fadeoff: fade from bright to dark
led.fadeon: fade from dark to light
led.slow: slow flash
led.medium: medium flash
led.fast: fast flash
led.1: single flash
led.2: two flashes
led.3: three flashes
led.4: four flashes
led.5: five flashes

cycles:
The number of times to repeat the mode sequence. 255 = forever.

Example:
//Set LED 0 to ON permanently
led.led(led.pwr, led.on, 255)

cpu.set_int_handler( {interrupt type}, {function} )

interrupt type:
cpu.INT_IRIDIUM_SIGNAL: Iridium modem has signal from 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 signal from 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.setlevel({level})

level:
-1 = None
 0 = Info
 1 = Debug

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.
 *
 */

pkcs5_pbkdf2:
/*-
 * 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]
========================================== */

header (byte): 0
<payload>
authentication code (10 bytes): HMAC-SHA256-80(<password>,<payload>)

-- set custom password, up to 32 bytes (interface 2)
core.setpassword("<password>")

-- reset default password
core.resetpassword()

A hexadecimal representation of the default password will be displayed if the operation is successful:
RP#password:0x<hexadecimal representation of password>

header (2 bytes): 0x00,0xFF
nonce (7 bytes, must be unique to key in use)
AES-CCM{
<payload>
authentication code (10 bytes): HMAC-SHA256-80(<password>,<payload>)
}
authentication field (from AES-CCM) (8 bytes)

-- set custom key, up to 32 bytes, represented as 64 hexadecimal characters (interface 3)
aes.sethexkey("<hexadecimal key>")

e.g.:
aes.sethexkey("37996FB42DDE61E890D2D88B9B5A83D16F3D35876D778E3E064677C37B50C424")

NOTE: DO NOT USE THE KEY ABOVE. If you require guidance on generating a secure key contact GSE for help.

A hexadecimal representation of the key will be displayed if the operation is successful:
M#RK#key:0x<hexadecimal representation of key>

By default if a key has been set, outgoing messages will be encrypted.  To clear the key, it can be set to an empty string:
aes.sethexkey("")

message type (byte): <0-255>
message length (byte): <0 - 255>
command (byte array): <destination length bytes>

message type (byte): 0
command length (byte): <0 - 255>
command (byte array): <destination length bytes>

message type (byte): 1
message length (byte): <0 - 255>
text message (byte array): <message length bytes>

message type (byte): 2
command length (byte): 6
setting number (uint16_t little endian): <0-65535>
setting value (int32_t little endian): <varies by setting, see setting descriptions>

message type (byte): 3
command length (byte): 0

message type (byte): 4
command length (byte): 0

header (byte): 0

header (byte): 1
destination length (byte): <0 - 255>
destination (byte array): <destination length bytes>
message (byte array): <byte array bounded by end of MO message>

header (byte): 2
interface version (byte): <version, currently: 2>
settings version (byte): <version, currently: 1>
setting 0 (signed 32 bit integer): <value of first setting>
...
setting N-1 (signed 32 bit integer): <value of Nth setting>

Current order:
0: defaultv
1: g_hdop // version 1 or later
2: g_timeout // version 1 or later
3: i_tx_timeout // version 1 or later
4: i_signal_timeout // version 1 or later
5: i_tx_retries // version 1 or later
6: sleep // version 1 or later
7: sos_sleep // version 1 or later
8: sleep_w_power // version 1 or later
9: led_mask // version 1 or later
10: i_rx_always // version 1,2 no effect, functional in version 3 or later
11: tx_altitude // version 1 or later
12: g_settle // version 1 or later
13: t_adc_id // version 1 or later (not currently used)
14: t_adc_threshold // version 1 or later (not currently used)
15: status_line // version 1 or later
16: low_bat_off // version 1 or later
17: g_hibernate_sleep // version 2 or later
18: cache_reports // version 2 or later
19: moving_sleep // version 3 or later
20: moving_thresh // version 3 or later
21: require_encrypted_mt // version 3 or later
22: g_on_always  // version 3 or later
23: sleep_w_bat  // version 4 or later
24: tx_seconds // Version 5 or later
25: report_format // Version 6 or later
26: extpwr_sleep // Version 8 or later: set this to a value other than 0 to override the
                 // "sleep" parameter between transmissions when external power is applied
27: extpwr_autostart // Version 9 or later: set this to 1 to trigger the unit to "power up"
                     // and start transmitting automatically the next time power is applied

header (byte): 3
interface version (byte): <version, currently: 2>

header (byte): 255
nonce (7 bytes)
AES-CCM{
header (byte)
message
}
authentication field (from AES-CCM) (8 bytes)

header (byte): 0
report (10 bytes)

header (byte): 4
report (10 bytes)

Remaining bits are Big Endian MSB 0.

bits 0-2: magic number
bits 3-25: longitude (encode: ROUND((longitude +180)*23301), decode: value/23301-180)
bits 26-31: heading (encode: ROUND(degrees/5), decode:  value*5)
bits 32-41: hours since midnight + 2 minute intervals (encode: ROUND(((hours*60) + minutes)/2), decode: (value*2)/60)
bits 42-63: latitude (encode: ROUND((latitude+90)*23301), decode: value/23301-90)
bits 64-69: speed (no conversion: meters/second, max 63 meters per second or 141 miles per hour)
bits 70-79: altitude (encode: meters/5, max 5110 meters or 16765 feet, decode: value*5)

header (byte): 5
report (18 bytes)

Please refer to google docs excel worksheet for bit ordering and fields