Creating Custom Forms for inReach Field Data Collection

What are Forms?
Forms are custom data collection fields for inReach Explorer and inReach SE. Data collected can then be sent as a satellite message and parsed into actionable, easy to understand information.

Why should my organization use Forms? 
Forms enable the transmission of vital information from remote parts of the world in a fast and uniform process, whereas manual data collection methods in remote areas can take hours or days to get back to HQ and even longer to organize.

What can be configured? 
Administrators are able to configure custom data fields with multiple choice-style options. For example, a forest fire unit can select which fuel is being consumed by a specific fire, such as upland grass, leaf litter or brush, allowing the command center to efficiently utilize their resources. Parsing code can then be used to sort and organize the raw data received from the field.

Creating Forms

WARNING! Some settings can make the device inoperable. Make sure to run tests before using the device in real-world situations.

There are undocumented keys which can be set. Make sure the correct keys are being used. If you make a mistake, reprogram the device with new firmware

Setting configuration settings will not work with recreational devices. Enterprise devices only

Form content, including the destination, must fit within an inReach message. Users will select the form based on its title (limit 30 characters). A template is strongly recommended to begin creating a custom form. The following section walks through the major components of creating a form.  Click here for a full template.

Form ID
Each form requires a unique ID number. This enables the developer to identify a specific form for editing, customization, etc.

<form id="1">     

Destination 
<destination>datacollection@mycompany.com</Destination>
<destination>inReachUserName@inreach.delorme.com</Destination>
<destination>datacollection@mycompany.com,+12075551212</Destination>
<destination></destination>

Data will be sent to this location. Multiple addresses can be specified using a comma. If this field is left blank, the message will only be available from the portal or via IPC.

Prefix
<prefix>STA-</prefix>

The prefix is added to the beginning of each message created. Each form does not need a prefix but it does make identifying which received message goes with which form.

Delimiter
<delimiter>*</delimiter>

This string is used to separate form fields when sending data. The default is a comma, but other characters or strings can be used. Remember that each one of these will be included for every field in the inReach message sent to the server.

Fields
For each field entry you specify a unique ID, name, type, any constraints, the default entry, and whether or not the field is required. Fields appear in the same order that they appear in tis file.

There are three types of fields: Text, Number or PickList.

Text Fields: 
A text field called “First Name” that is optional but must be under 25 characters in length:
<field id="1">
<name>First Name</name>
<type>Text</type>
<length>25</length>
<required>N</required>
</field>

The same field, but this time it is required, not optional: 
<field id="1">
<name>First Name</name>
<type>Text</type>
<length>25</length>
<required>Y</required>
</field>

The same field, but this time with “Fred” as the default name: 
<field id="1">
<name>First Name</name>
<type>Text</type>
<length>25</length>
<required>Y</required>
<default>Fred</default>
</field>

Number Fields: 
To collect a Number field called “Tree Count” between 1 and 10: 
<name>Tree Count</name>
<type>Number</type>
<Min>1</Min>
<Max>10</Max>
<required>Y</required>
</field>

PickList Fields
To collect a PickList field called “Fruit”: 
<name>Fruit</name>
<type>PickList</type> 
<Value>Apple</Value>
<Value>Orange</Value>
<Value>Banana</Value>
<Value>Pear</Value>
<required>Y</required>
</field>

To collect the same value but default to “Orange”:
<name>Fruit</name>
<type>PickList</type> 
<Value>Apple</Value>
<Value>Orange</Value>
<Value>Banana</Value>
<Value>Pear</Value>
<required>Y</required>
<default>Orange</default>
</field>

When you combine all of the above components, your form is ready for testing and implementation.  Click here for a full template.

Parsing Data

As the creator of the inReach form you have prior knowledge of the forms (which prefix goes with which form) and you know the order and mapping of each field. With this knowledge a script can be written to parse and easily to interpret the raw data received from a forms message. There are several ways through which this can be accomplished. You could write a Perl script to parse the message. In  this example  you copy and paste the message into the script and the script converts the message into readable text. A more automated way is to use an Outlook macro to parse the message as it comes in from the field.  This Outlook macro example  waits for a message to come into the inbox, parses the message and displays the information in readable text. Either script could be updated to append records to a database or spreadsheet.

Syncing Forms to Your Devices

Getting your newly created form onto an inReach is not the same as performing a standard sync. You will need to use the following steps:

1. Save the form file as a .sec extension
2. Plug your inReach into a computer via the supplied USB cable
3. Power on the inReach
4. Run the inReachSEConfigWrite application. This application will also work with inReach Explorer
5. Select File >Open
6. Select your form file
7. Select the Program inReach button. A progress dialog box will appear
8. The Programmed Devices Total will increase by one when the device is ready
9. Select Done if you only need the form on one device, or plug in another inReach to continue programming
10. Close the application.
    

Form Template Example

<?xml version="1.0" encoding="utf-8"?>
<root>
<table tableName="Forms" version="1">
<form id="1">
<destination></destination>
<delimiter>*</delimiter>
<title>Status</title>
<destination>Name@company.com, First.last@company.com</destination>
<prefix>STA-</prefix>
<delimiter>|</delimiter>
<field id="1">
<name>Fire Size</name>
<type>Number</type>
<Min>1</Min>
<Max>100000</Max>
<required>N</required>
</field>
<field id="2">
<name>Status</name>
<type>PickList</type>
<Value>Enroute</Value>
<Value>OnScene</Value>
<Value>Contained</Value>
<Value>Controlled</Value>
<Value>Ret. Station</Value>
<Value>Available</Value>
<required>Y</required>
<default></default>
</field>
</form>
<form id="2">
<title>First Report of Fire</title>
<field id="1">
<name>Section</name>
<type>Number</type>
<Min>1</Min>
<Max>36</Max>
<required>N</required>
</field>
<field id="2">
<name>Township</name>
<type>Text</type>
<length>3</length>
<required>N</required>
</field>
<field id="3">
<name>Range</name>
<type>Text</type>
<length>2</length>
<required>N</required>
</field>
<field id="4">
<name>Range Dir</name>
<type>PickList</type>
<Value>E</Value>
<Value>W</Value>
<required>N</required>
</field>
<field id="5">
<name>Fuel Consumed</name>
<type>PickList</type>
<Value>(leave blank)</Value>
<Value>Upland Grass (L/1)</Value>
<Value>Lowland Grass (N/3)</Value>
<Value>Leaf/Needle Litter (E/9)</Value>
<Value>Slash Moderate Loading (J/12)</Value>
<Value>Conifer Regen/Brush (Q/8)</Value>
<Value>Peat</Value>
<Value>Other</Value>
<required>Y</required>
<default>(leave blank)</default>
</field>
<field id="6">
<name>Incident Commander (Last Name)</name>
<type>Text</type>
<length>20</length>
<required>N</required>
</field>
</form>
<form id ="3">
<title>Aircraft request</title>
<destination>Name@company.com, First.last@company.com</destination>
<prefix>ACR-</prefix>
<delimiter>*</delimiter>
<field id="1">
<name>Fire Size</name>
<type>Number</type>
<Min>1</Min>
<Max>100000</Max>
<required>N</required>
</field>
<field id="2">
<name>Fuel Type</name>
<type>PickList</type>
<Value>Pine Regen</Value>
<Value>Upland Grass</Value>
<Value>Lowland Grass</Value>
<Value>Brush</Value>
<Value>Conifer</Value>
<Value>Hardwood</Value>
<required>N</required>
<default>Hardwood</default>
</field>
<field id="3">
<name>Values Threatened</name>
<type>PickList</type>
<Value>Structures</Value>
<Value>Resources</Value>
<Value>Evacuation</Value>
<required>N</required>
<default>Structures</default>
</field>
<field id="4">
<name># Heli</name>
<type>Number</type>
<Min>1</Min>
<Max>10</Max>
<required>N</required>
</field>
<field id="5">
<name># Air Tankers</name>
<type>Number</type>
<Min>1</Min>
<Max>10</Max>
<required>N</required>
</field>
<field id="6">
<name># SEAT</name>
<type>Number</type>
<Min>1</Min>
<Max>10</Max>
<required>N</required>
</field>
<field id="7">
<name>Ground Contact(Last Name)</name>
<type>Text</type>
<length>20</length>
<required>N</required>
</field>
</form>
<form id="4">
<title>WxObs</title>
<destination>Name@company.com, First.last@company.com</destination>
<prefix>WxF-</prefix>
<delimiter>|</delimiter>
<field id="1">
<name>Temp</name>
<type>Number</type>
<Min>-15</Min>
<Max>150</Max>
<required>N</required>
</field>
<field id="2">
<name>RH</name>
<type>Number</type>
<Min>0</Min>
<Max>100</Max>
<required>N</required>
</field>
<field id="3">
<name>MFWind_mph</name>
<type>Number</type>
<Min>0</Min>
<Max>100</Max>
<required>N</required>
</field>
<field id="4">
<name>FL_feet</name>
<type>Number</type>
<Min>5</Min>
<Max>100</Max>
<required>N</required>
</field>
<field id="5">
<name>ROS_ft_min</name>
<type>Number</type>
<Min>0</Min>
<Max>2500</Max>
<required>N</required>
</field>
<field id="6">
<name>Fire_Type</name>
<type>PickList</type>
<Value>Creeping</Value>
<Value>Running</Value>
<Value>Torching</Value>
<Value>Crowning</Value>
<required>Y</required>
<default></default>
</field>
</form>
</table>
</root>

PERL Script Example
$message = 'ACR,6666,6,1,5,6,4,Abc'; #copy inReach message here

@Status=('Enroute', 'OnScene', 'Contained', 'Controlled', 'Ret. Station', 'Available');
@FuelType=('Pine Regen', 'Upland Grass', 'Lowland Grass', 'Brush', 'Conifer', 'Hardwood');
@ValuesThreatened=('Structures', 'Resources', 'Evacuation');

   chomp $message;
   @fields = split(/,/, $message); # comma is the separator

#Status Message 
   if ($fields[0] eq 'STA') {
    print "Status---", ", Fire Size: ", $fields[1]," acres, Status: ",$Status [$fields[2]-1], "\n";
    # subtract 1 from the array index since perl arrays start at zero and Form pick list start at 1
   }
            
 #Aircraft Request Message 
   if ($fields[0] eq 'ACR') {
    print "Aircraft Request---", ", Fire Size: ", $fields[1]," acres, Fuel Type: ",$FuelType[$fields[2]-1],
    ", Values Threatened: ", $ValuesThreatened[$fields[3]-1],", No. Heli: ",$fields[4],", No. AirTankers: ",
    $fields[5],", No. SEAT ",$fields[6],", Ground Contact ",$fields[7],  "\n";
   # subtract 1 from the array index since perl arrays start at zero and Form pick list start at 1
   }

Outlook Macro Script Example

' Place this code in the "ThisOutlookSession" class module

' The code will:

' Monitor the Inbox
' Parse emails from inReach from two of the example forms
' Print the data entered in the form replacing pick list values with the actual values
' Note: Arrays in VBA start at 0 where form pick list start at 1

Private WithEvents olInboxItems As Items

' Application_Startup() is a reserved function that will automatically
' be called when Outlook starts.
'
Private Sub Application_Startup()
    Set olInboxItems = Session.GetDefaultFolder(olFolderInbox).Items
End Sub

'
' This event is fired when the Inbox receives a new message
' (it can also be fired when manually moving a message from
'  another folder back to the inbox)
'
Private Sub olInboxItems_ItemAdd(ByVal Item As Object)
  
    Dim olMailItem As MailItem
    '
    ' Only inspect mail items
    ' Ignore appointments, meetings, tasks, etc.
    '
    If TypeOf Item Is MailItem Then
        Set olMailItem = Item
        Dim strAddr As String
        Dim strArray() As String
        Dim strLineArray() As String
       
        Dim Status() As String
        Status() = Split("Enroute,OnScene,Contained,Controlled,Ret. Station,Available", ",")
       
        Dim FuelType() As String
        FuelType() = Split("Pine Regen,Upland Grass,Lowland Grass,Brush,Conifer,Hardwood", ",")
        Dim ValuesThreatened() As String
        ValuesThreatened() = Split("Structures,Resources,Evacuation", ",")
       
        On Error Resume Next
       
        If Not olMailItem Is Nothing Then
            strLineArray = Split(olMailItem.Body, vbCrLf) 'Array of lines
            strArray = Split(strLineArray(0), ",") 'First line contains the form message
           
            ' Status Form
            If strArray(0) = "STA" Then
                MsgBox ("STATUS --- Fire Size: " & strArray(1) & " acres, Status: " & Status(strArray(2) - 1))
            End If
           
            ' Aricraft Request Form
            If strArray(0) = "ACR" Then
                MsgBox ("AIRCRAFT REQUEST--- Fire Size: " & strArray(1) & " acres, Fuel Type: " & FuelType(strArray(2) - 1) & ", Values Threatened: " & ValuesThreatened(strArray(3) - 1) & ", No. Heli: " & strArray(4) & ", No. AirTankers: " & strArray(5) & ", No. SEAT " & strArray(6) & ", Ground Contact " & strArray(7))
            End If 
        End If
    End If
   
    Set Item = Nothing
    Set olMailItem = Nothing

End Sub