ClearWatch 250

The ClearWatch 250 is the smallest self contained Iridium tracker in the world! It can transmit your location from anywhere in the world and is built on the latest satellite, antenna, and electronics technology.

Details

• Dimensions are miniscule at 45 mm x 45 mm x 34mm including battery, modem, and antenna (OEM version), 45mm x 45 mm x 20 mm including battery and modem (both without external casing)
• SiRFstarIV GPS with an amazing -163dBm sensitivity
• AES 256-bit encryption supported (optional)
• Rechargeable Lithium Polymer battery (2.4 Ah, up to 1000 position reports)
• Integrated omnidirectional helical antenna (high gain ceramic patch antenna for OEM model)
• Over the air configuration of the terminal
• USB, RS-232 and Bluetooth connections for programming
• Full 2 way communications network
• Bluetooth 4.0 (LE) smartphone connectivity for messaging and configuration
• Truly global coverage with the Iridium satellite network
• 11 bytes per position report (altitude can be disabled to reduce size to 9 bytes) (including latitude, longitude, speed, heading, battery level, time, altitude, Alert & Checkin status)

Interfaces

• DC Power (7V to 36V DC) @ 1A max
• USB Interface (Power, Serial Console/Logging, Firmware Update)
• RS232 Interface (Serial Console/Logging)
• Bluetooth 4.0 Low Energy
• 2 Relay Outputs @ 250mA (Open Drain)
• 2 Analog Inputs (0V to 30V DC)

Battery Life Calculator

The battery life calculator is hosted on Google Docs where you can download a copy or copy the sheet into your own Google Docs account

Battery Life Calculator

Getting Started

Service

The ClearWatch 250 is powered by an Iridium 9602 SBD modem which requires Iridium SBD service to send messages. We can provide this or you may choose an Iridium SBD service provider of your choice. If used with the portal, ensure that provider correctly configures the DirectIP address and port as described here:Device Routing IP Addresses and Ports.

The current configuration appropriate for the ClearWatch 250 for Iridium DirectIP is: 66.165.183.84:4780

Portal Configuration

In order to send and receive messages to your ClearWatch 250 through the portal it will first need to be Added as an asset

Power Up

Out of the box your unit should be in off or storage mode. In order to power it up and start transmitting you will need to hold down the power button until power and GPS lights “fade up” (dark to bright). When you release the button it will start a position report cycle. The states of which are described below:

While the unit is powered on, it will go through progressive stages of acquiring signal, transmitting, and sleeping, as indicated by the Power and Message LED’s.

1. Upon power up or wakeup from sleep, the Power LED will “fade up” until initialization is complete, after this the LED will indicate battery state (flashing up to 5 times if the battery is full).
2. Next, when GPS is enabled the GPS LED will fade up until satellites are acquired, at which point the number of flashes indicates the number of satellites acquired (up to 5) until a fix achieved, then the LED will stay on, solid.
3. Next, the Iridium modem will be enabled and the Satellite LED will fade up until signal is acquired. Once iridium signal is acquired, the LED will flash 1-5 times indicating signal level. The LED will stay on solid once a transmission has been successful.
4. If only one report or message was pending the unit will then sleep until the next transmission. On battery all LEDs will turn off. If plugged into an external power source, LEDs will reflect last state achieved. The last status can be displayed by briefly pressing the power button if the unit is on battery.

If transmission was successful your unit should appear on the map at its current location. See the “Terminal Behavior” section below for more details on button and LED behavior.

ClearWatch 250 Configuration Through Portal

Once an asset is configured and running, parameters can be set using the “Send Command” functionality. This will allow you to configure a number of parameters that control the behavior of the unit including:

• Normal Reporting Interval
• Timeouts for GPS and Iridium
• Number of attempts to make transmitting
• Whether to include altitude in reports (with altitude reports are 11 bytes, without 9 bytes)

Configure

1. Click on the down arrow next to the asset in the Assets list on the left. The default view will be for “Set Parameters.”
2. Click the checkboxes next to the parameters to update and fill in values desired.
3. Click “Set Parameters” button on the left below the settings list.

Settings can be later confirmed by clicking on the “Get Parameters” button on the top right of the “Set Parameters” screen. The Last Queried and Last Response values will indicate the last time parameters were requested and the last time they were successfully sent from the Micro. The last successfully requested set of parameters will be used for default values for the settings.

Drivers

Windows

32-Bit Windows (XP, Vista, 7, 8)

64-Bit Windows (XP, Vista, 7, 8)

• 32-Bit Windows (XP, Vista, 7, 8)

• 64-Bit Windows (XP, Vista, 7, 8)

Mac OS X / Linux

No drivers required.

Serial Interface

RS-232 Interface Default Settings: 115200 baud, 8 bits, no parity, 1 stop bit, no flow control

Windows (USB-only)

1. Install the appropriate driver package.

• 32-Bit Windows (XP, Vista, 7, 8)

• 64-Bit Windows (XP, Vista, 7, 8)

1. After installing you can connect the unit using the USB cable, Windows should load the USB-Serial adapter driver.
2. Connect to the COM port for the unit using a terminal emulator.
   • To do this, grab a copy of TeraTerm Pro or use your favorite terminal emulator.
   • Go into the device manager on your machine. Under Ports (COM & LPT) you should see something called ClearWatch 250 Serial Port, and the COM port number next to that.
   • Take that number and open the terminal emulator. If TeraTerm Pro it should show a “New Connection” window by default. Select the “Serial” radio button and then the COM Port from the drop down menu. Click OK.

Windows (RS-232)

1. Connect the RS-232 connector. NOTE: Connect external power to prevent the unit from powering down after the end of a transmit cycle.
2. Connect to the COM port for the unit using a terminal emulator. To do this, grab a copy of TeraTerm Proor use your favourite terminal emulator.

If using an alternate terminal emulator the interface parameters are: 115200 baud, 8 bits, no parity, 1 stop bit, no flow control

If TeraTerm Pro it should show a “New Connection” window by default. Select the “Serial” radio button and then the COM Port from the drop down menu. Click OK.

Firmware Update

Please contact support first to determine whether a firmware update may be necessary.

Windows (USB-only)

1. Install the appropriate driver package.

   • 32-Bit Windows (XP, Vista, 7, 8)

   • 64-Bit Windows (XP, Vista, 7, 8)

2. After installing you can connect the unit using the USB cable, Windows should load the USB-Serial adapter driver.

3. Connect to the COM port for the unit using a terminal emulator.

   • To do this, grab a copy of TeraTerm Pro TeraTerm Pro or use your favorite terminal emulator.
   • USB Serial: Go into the device manager on your machine. Under Ports (COM & LPT) you should see something called ClearWatch 250 Serial Port, and the COM port number next to that. Take that number and open the terminal emulator. If TeraTerm Pro it should show a “New Connection” window by default. Select the “Serial” radio button and then the COM Port from the drop down menu. Click OK.
   • If the unit is transmitting you should see lines scrolling past starting with G# and I# (G=GPS, I=Iridium). Otherwise, you may see nothing, or once every 10 seconds a B# line. You can check that the unit is responding by hitting enter, you should see it show a prompt for each enter that looks like a >
   • Leave this open for the moment.

4. Download the firmware link provided (please contact GSE, support for a copy)

5. Run the “flash_firmware” script in the extracted folder, it should bring up a window asking you to to issue a command to the unit, don’t hit enter yet.

6. Return to the terminal window and put the unit into firmware upload mode (it will stay in this mode for 30 seconds) by typing:

   • pmu.reboot()
   • (followed by enter)
   • Windows should then try to load the firmware upload driver.

7. When the driver loading is complete, hit enter in the window for the “flash_firmware” script.

You should see a progress bar as the firmware is uploaded, it should end with something similar to:

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

If the progress bar does not appear and it is unable to find the device, you can close/reopen the serial connection and re-attempt the “pmu.reboot()” command. If other errors are encountered, please contact support.

MacOS X (USB-only)

1. Download the firmware link provided (please contact GSE, support for a copy)

2. Unzip the file and double click on flash_firmware_osx. It will display “connect/prepare device to be flashed and press any key,” don’t press enter yet.

3. Open a new window in Terminal.app which was just opened by the script we started (flash_firmware_osx)

4. Type the following into the new terminal window and hit enter:

    ls /dev/tty.usbmodem*
   

5. Now plug in your ClearWatch 250 and run the same command again. Make note of the new entry you see (i.e.: /dev/tty.usbmodem14121), you will need this name later as

6. Connect to this device using your favorite terminal emulator (kermit, screen, etc..)

   For screen:

    screen device-name
   

   For example:

    screen /dev/tty.usbmodem14121
   

7. Type the following into the screen followed by enter:

    pmu.reboot()
   

8. While the power LED on the ClearWatch 250 is flashing on/off once each second, hit enter in the flash_firmware_osx window.

You should see a progress bar as the firmware is uploaded, it should end with something similar to:

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

If the progress bar does not appear and it is unable to find the device, you can close/reopen the serial connection and re-attempt the “pmu.reboot()” command. If other errors are encountered, please contact support.

Terminal Behavior

The front interface panel has three buttons and 5 lights. Behavior is described below.

Button behavior

When you depress the Power button for more than 1 second, the unit will either turn off if it is currently on and go into a deep sleep without transmitting, or if it is currently sleeping, will wake the unit and immediately transmit a position.

When you depress the Check In button WHILE the unit is on, the next successful transmission report will contain a bit flag indicating that it is a Check In message. This mode will be cleared once a successful transmission is made. The MSG light will begin flashing slowly.

When you depress the Config + Check In button together for Alert mode, the unit will IMMEDIATELY begin transmitting it’s current location even if it was sleeping. The MSG light will begin flashing rapidly. The unit will also use change the sleep interval to the value specified by “sos_sleep” time in seconds indicated in the “settings” function below. To exit Alert mode, depress the Config + Check In button together again and the MSG light will turn off again.

LED modes

Troubleshooting

Q: Why am I not receiving position reports?

A: There are a number of possible causes for a lack of reports being received.

1. The unit must have active Iridium SBD service. Ensure the unit been activated for Iridium SBD service.

2. Routing for the device may be configured incorrectly. Ensure SPNet configuration set for the Device Routing IP Addresses and Ports

3. The unit may be low on power or off. Is the unit powering up and attempting a transmit cycle as described in the getting started section? If not, follow the getting started section to turn the unit on. If the unit only turns on for less than 10 seconds, make sure the unit has adequate charge (while on, Power LED should flash 2-5 times, if only flashing once, battery may be low).

4. The unit does not have a clear view of the sky. Ensure the unit have a clear view of the sky with the antenna pointed up and not obscured.

Console/Terminal Behavior

The core functionality is driven by a eLua console that connects to the RS232, USB CDC, and BLE SPP ports. Any characters entered on any of the ports will be echoed to all ports. From this console, you can run your first script by simply typing ‘print(“Hello World!”)’ and pressing enter to execute.

To connect to RS232, simply connect to a RS232 level port (+/- 12VDC, not TTL level) at 115200,8N1

To connect via USB, simply connect and install drivers from this page if you are running Windows, or if you are running Linux or Mac, the drivers are already included.

To connect via Bluetooth 4.0 (BLE), you will need to utilize developer libraries to achieve connectivity. As there is not a Serial Port Profile standard for Bluetooth 4.0, the utilized standard is documented here:

Bluetooth Low Energy Serial Profile Standard

We do force pairing/authentication prior to allowing reading/writing the serial service. Also, when the unit is placed into low power mode, or is sleeping between position reports, the BLE module stays active and waiting for a connection. If you place the unit into factory sleep mode, then BLE will be powered off. Also, if an active connection is established, the BLE module will stop the unit from going to sleep, or will wake the device from sleep to process commands. To ensure good battery life, your application should disconnect automatically when it is not in use or becomes idle.

Q: Why am I getting incorrect position reports?

A) There are two likely causes for this situation:

1. The DirectIP routing may be configured incorrectly. Ensure that the unit is configured for the Device Routing IP Addresses and Ports

2. If you are north of 45 N latitude or south of 45 S latitude and are getting incorrect locations and have correct routing information, contact support for a firmware update.

Lua functions

These options can be sent to the terminal via the “Send Command” function within the tracking platform, or 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 most language features are enabled except for math and os libraries.

NOTE: Commands sent from the tracking platform will not show command output anywhere other than on the serial console. However, messages can be composed using the gsattrack functions and the iridium transmit function can be used to send them.

GPS functions

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

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)

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.

Iridium functions

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

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

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) : ??

NOTE: need to add diagram here showing orientation of unit and maybe change the names of these to be more intuitive.

Battery functions

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

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

LEDs

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)

Interrupts / Event Handlers

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

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

https://github.com/elua/elua/blob/master/LICENSE

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

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

COCOM Limits

COCOM limits are a GPS limitation by international law to disable GPS chipsets at high altitudes or high speeds.

The ClearWatch 250 will stop reporting if the unit exceeds 1,000 knots AND exceeds 18,000 meters. Both of these limits must be exceeded for COCOM limits to be enabled which will disable the internal GPS receiver until one of the two limits returns to normal.

OEM Model

Measurements

45 mm x 45 mm x 34mm including battery, modem, and antenna

Items included

• Ceramic patch antenna, dual-tuned for Iridium and GPS
• ClearWatch 250 main board
• Iridium 9602 SBD
• breakout board (with VCC, GND, Relay 1,2 and ADC 1,2 and LED status, USB, RS-232)
• 2400 mAh lithium polymer battery

Interfaces

• DC Power (6V to 36V DC) @ 1A max
• USB Interface (Power, Serial Console/Logging, Firmware Update)
• RS232 Interface (Serial Console/Logging)
• 2 Relay Outputs @ 250mA (Open Drain)
• 2 Analog Inputs (0V to 30V DC)

Cable Pinout

Message Formats

Mobile Terminated (MT)

Max Length (interface 2): 255 bytes

Byte ordering is little-endian MSB 0 unless otherwise noted.

Authenticated Message Type

Interface Version: 2 (or later)

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

Where an HMAC-SHA256 is computed over the (header byte not included) using a password/key shared by the device and server, and is truncated to the first 10 bytes (80-bits).

Passwords can be set on the on the unit using the Lua commands:

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

Encrypted Message Type

Messages can also be encrypted using AES-CCM mode (using no additional auth data, 7 octet nonce and an 8 octet authentication field).

The payload messages below are the same but are wrapped in encryption following the format:

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)

No default key or password is set on the unit so a key must be set to enable the functionality.

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

Payload Messages

Generic message format:

Interface Version: 2 (or later)

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

Lua Command:

Interface Version: 2 (or later)

Maximum: 1 lua command per MT message.

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

Text Message:

Interface Version: 2 (or later)

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

Change Setting:

Interface Version: 2 (or later)

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>

Request Settings:

Interface Version: 2 (or later)

This message will request the current settings be sent in the next transmit cycle.

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

Request Interface Version:

Interface Version: 2 (or later)

This message will request just the interface version be sent in the next cycle.

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

Mobile Originated (MO)

Formats are Little Endian MSB 0 unless otherwise noted.

Position Report:

Interface Version: 1 (or later)

header (byte): 0

Reserved for GSatTrack

Text Message:

Interface Version: 1 (or later)

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>

Settings Dump:

Interface Version: 1 (or later)

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

Interface Version: 2 (or later)

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

Encryption Wrapped Message:

Interface Version: 3 (or later)

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

Mobile Originated Position Format

Wikipedia Protocol Definition GSE_Open_GPS_Protocol

Copyright (c) 2017 Global Satellite Engineering, Inc. Permission is hereby granted, free of charge, to any person to deal in the message format without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the message format, to send and receive messages formatted according to the message format, and to permit persons to whom the message format is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies of documentation describing the message format.

THE MESSAGE FORMAT 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 MESSAGE FORMAT OR THE USE OR OTHER DEALINGS IN THE MESSAGE FORMAT.

10-byte GSE proprietary format (settings.report_format=0):

This protocol is a highly compressed format that is not publicly released, but is available through a decoding service. Interface Version: 3 (or later)

header (byte): 0
report (10 bytes)

10-byte Position (settings.report_format=1):

Google Docs Excel Worksheet: Google Docs 10 Byte Format Worksheet

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)

18-byte High Resolution Position (settings.report_format=2):

Google Docs Excel Worksheet: Google Docs 18 Byte Format Worksheet

Interface Version: 3 (or later)

header (byte): 5
report (18 bytes)

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

See Also

Supporting Features

• Assets