Introduction

The SUT protocol can be used between a Lommy device and a Server, to exchange data, commands and parameters.
SUT is a pure text protocol. 


SUT protocol

Any telegram consist of one or more comma-separated Name/Value item(s).

Incoming message could look like this:

TNO[-1],ID[1315000100],SM[200000],GSM[2,{238,66,95B2,2F01,-70},{238,66,60E1,2F01,-82}],CAP[3243,3158,3158],TEMP[26]*CRC[2799]

 

NameValue items:

Name: Use uppercase characters A-Z. The – sign are also allowed, ex: VPORT-STATUS
Value: Can be a single entry, a comma-separated list of entries, records or a mix of these.
The signs { and } are used to mark “records”.

TNO[-1]
ID[1315000100]
GSM[2,{238,66,95B2,2F01,-70},{238,66,60E1,2F01,-82}]
PARAM[{REPORT-INTERVAL,86400},{MOVE-WAKEUP,0},{LIGHT-SENSOR,0},{ECHO-MODE,0}]

 

CRC item

If the CRC item is included in the packet, it must always be the last item and preceeded by a * delimiter sign.


Flow

Data: TNO[-1],ID[1315000100],GSM[2,{238,66,95B2,2F01,-70},{238,66,60E1,2F01,-82}],CAP[3243,3158,3158],TEMP[26]*CRC[2799]
Response: ACK[-1],TIME[20160207124721]

The server has to respond with an ACK to that message TNO, otherwise the transmission will be deemed unsuccessful on the unitThe TNO will only change if the device receives an ACK from the server.

 

The server can append additional data to the response. This is also the way to change/set parameters and commands. The unit will respond with an ACK upon receiving the additional data.

Data: TNO[-1],ID[1315000100],GSM[2,{238,66,95B2,2F01,-70},{238,66,60E1,2F01,-82}],CAP[3243,3158,3158],TEMP[26]*CRC[2799]
Response: ACK[-1],TIME[20160207124721],PARAM[{REPORTINTERVAL,172800},{GPS-TIMEOUT,180}],CMD[{RESET,}]
Data: ID[1315000100],ACK[-1]

Unit Data telegram (incoming data)

TNO int MANDATORY
The message number (-1 - -9999)
TNO[-552]
ID string MANDATORY

Device ID
ID[1234567890]

TRANS int  

The transportation method.
0: (default) GPRS
1: WiFi
2: UMTS
3: LTE
TRANS[1]

ECHO structure  

ECHO information.
Format: ConnStatus,ID
ECHO[0,1122334455]
- the device cannot connect to any echo tags. The last one heard was id=1122334455
ECHO[1,9988776655]
- the device has connected to echo id=9988776655

ICCID string  

ICCID number of the sim card
ICCID[8945020184520719812]

RST int   

Reset cause.
RST is automatically included in the first DataTelegram after power-reset.
RST[1]

FWVER string   

Firmware Software version.
FWVER is automatically included in the first DataTelegram after power-reset.
FWVER[67]

VER string   

Application Software version.
VER is automatically included in the first DataTelegram after power-reset.
VER[10]

APPTYPE string   

Application Software type.
APPTYPE is automatically included in the first DataTelegram after power-reset.
APPTYPE[2]

TIME string  

The date/time in the device. Format: YYYYMMDDHHmmss
If the date/time is not known by the device, this field will not be included.
TIME[20140107103208]

SM UInt64 MANDATORY 

Statemask bits of the device. This value must be hexadecimal.
SM[0]

GSM structure MANDATORY 

Gsm cell information.
Format: ServingTA,{ServingCellMCC,ServingCellMNC,ServingCellID,ServingLAC,ServingRssi},{MCC,MNC, cellID,LAC,rssi},...
The first value is "ServerTA". Next, a list of up to 16 GSM cells will follow.
The first in the list, will be the serving cell. The rest holds the data for up to 15 neighbourgh stations.
cellID and LAC are hexadecimal values.
GSM[2,{238,2,7D7A,0036,84},{238,20,1AA6,1772,18},{238,1,120B,011A,12},{238,20,1D0A,1773,7},{238,1,1309,011A,7}]

GPS structure   

Gps data.
Format: TimetoFix,Lat,Lon,Speed,Radius,Direction
TimeToFix in seconds.
Lat is Latitude
Lon is Longitude
Speed in meters/hour
Radius in meters
Direction in degrees
Note: Speed and Direction will be lank if speed is below 10 Km/h!
ex: GPS[10,N56.04.8480,E9.46.4879,86,0,248]

CAP structure MANDATORY

Information about voltage.
Format: VStart,VEnd,VDelay
"VStart" : measured just before turning the gsm module on.
"VEnd" : measured just after turning the gsm module off.
"VDelay" : measured 100s after turning the gsm module off.
All measurements are in milli-volts.
The measurements relate to the previous report session.
CAP[3243,3173,3171]

TON int MANDATORY 

The number of seconds the GSM module was turned on.
The measurement relate to the previous report.
TON[41]

TEMP int MANDATORY

The temperature measured by the device. In degrees celcius.
The parameter TEMP-INPUT determines the source of the measurement.
TEMP[23]

ANA array  

The voltage measured at the two inputs. In mV.
ANA[23,8760]

TAG structure  

Information about tag's.
Format: {Type,ConnStatus,ID,Status,Rssi,Time},...
TAG[{2,0,1224000010,0,-71,20131223100723},{2,1,1325000100,0,-83,20131223100721}]

VPORT-STATUS structure  

Information about VPort's.
Format: {Type,ID,Version,NoOfMeas,Meas(0),Meas(1),...,Time},...
"Type" : (see VPort documentation elsewhere)
"ID" : ID of the VPort device.
"Version" : Version. (10 = 0.10)
"NoOfMeas" : No of measurement values to follow.
"Meas(x)" : Comma-separated measurement values.
"Time" :
VPORTSTATUS[{2,1330011209,10,2,10,20,20140103143800},{1,1330011210,10,2,11,21,20140103143830}]

ALARM array  

Alarm ID's in the device.
0 : no alarm
8 : no wolf heard
ALARM[8]

MBIT structure  

"Moving-bits" information covering the latest REPORT-INTERVAL-MOVE period.
Format: [Time,NoOfBits,Value]
"Time" : Timestamp of the first "moving-bit"
"NoOfBits" : number of valid bits in "Value"
"Value" : hexadecimal value (Uint64). Each bit covers 6 minutes and indicates if there has been movement in that period.
MBIT[20141215100721,20,8D3]
In this example, there was detected movement in periods (starting from 0): 0,1,4,6,7 and 11.
All these periods covers 6 minutes each, and the first bit-period (period 0) started 2014/12/15 10:07:21

CRC UInt16 MANDATORY

crc calculation of the message.
Note that the CRC must be the last item in the telegram, and preceded with a "*"
This value must be hexadecimal.

 


Server Response telegram (outgoing data)

ACK int MANDATORY

Acknowledge to a Data telegram (-1 - -9999)
ACK[-552]

NAK int  

Not-Acknowledge (-1 - -9999)
NAK[-552]

TIME string  

Set the date/time in the device. Format: YYYYMMDDHHmmss
TIME[20140107111231]

ACT UInt32  

Actions/Features to be enabled/disabled in the device. Each action has a bit:
0x00000001 = Include sim card ICCID number in next report
0x00000002 = Enable BEACON
0x00000004 = Include Application SW type and version in next report
0x00000008 = Include Firmware SW version in next report
0x00000010 = Enable Extended Cell Info (SNMON)
0x00000020 = Enable "AutoBeacon" mode.
0x00000040 = Enable digital input lav→høj event
0x00000080 = Enable DateTime info in TAG/VPORT fields
0x00000100 = Include ANA in reports.
This value must be hexadecimal.
These bit assignments are shared with other projects, also using the SUT protocol!
Enable multiple Actions/Features: 0x2 + 0x20 + 0x80 = 0xA2
ACT[A2]

WEEK  array  

Sets a Weekday-calendar in the device. This will disable the traditional report interval
system.
The time entries will define 1-4 times to report each weekday (monday-saturday).
If no entries are given (WEEK[]), the calendar is not used, and the device will revert to the standard report interval.
Format: {HH,mm},...
WEEK[{8,0},{9,0},{10,0},{11,0}]

SUN  array  

Sets a Sunday-calendar in the device. This will only work if a Weekday-calendar is also defined.
The time entries will define 0-4 times to report on sundays.
If no entries are given (SUN[]), there will be no reports on sundays.
Format: {HH,mm},...
SUN[{15,0}]

SEED  UInt16  

Change seed value in the device. (Initial value in crc calculations.)
This value must be hexadecimal.
SEED[1234]

ECHOLIST array  

Set a echo-tag list in the device. (see description of ECHO mode feature)
ECHOLIST[4711,4712,3091210008]

PARAM array  

Set a parameter value in the device. (see description of Parameters)
Format: {ParName,ParValue},...
PARAM[{REPORT-INTERVAL,25},{ECHO-MODE,2}]

CMD array  

Send a command to the device. (see description of Commands)
CMD[{RESET}]

WOLFLIST array  

Set a wolf-tag list in the device. (see description of the WOLF feature)
WOLFLIST[4711,4712,3091210008]

 


ACK telegram (incoming data)

Used only if Response telegram carries more than ACK and TIME fields. For example when sending parameters and/or commands.

ACK int MANDATORY
Acknowledge to a Response telegram carrying data.
ex: ACK[-552]

 


Battery Calculation

Unit Initial capacity Daily idle and discharge
Lommy Eye 3-year battery 3650 mA 0,8 mAh
Lommy Eye 15-year battery 19000 mAh 1,5 mAh

 

The battery consumption needs to be calculated on the server. The calculation needs to happen every time a report is received.

To do this, we'll need the first two values from CAP[] ("VStart" & "VEnd").

(( VStart - VEnd )/70)*((70*5)+(35/2))/3,6/1000

Example: (15-year battery)

CAP[3243,3173,xxxx]

((3243-3173)/70)*((70*5)+(35/2))/3,6/1000 = 0,1020833333

19000 - 0,1020833333 = 18999,8979166667

This is the remaining battery capacity "18999,8979166667", next time subtract from this value.

Additional values:

If the GPS module is enabled for that report, subtract furhter "1" mAh from the remaining battery capacity.

Each day subtract the "Daily idle and discharge" value, from the remaining battery capacity.