Intro

The 4th generation of the Syrus family of devices, Syrus IoT Telematics Gateway, can be programmed with a propietary language called Syruslang.

With Syruslang you can create custom definitions to quickly interface with the device and its internal components (network, inputs/outputs, accelerometer, gnss, etc) in order to customize the Syrus' reporting behavior.

The custom definitions are part of a Smart Event Engine, which constantly evaluate conditions.

For examples checkout our Github Repo (opens new window).

Quick 5 minute introduction that goes over the main points of this documentation.

SyrusJS

Syruslang runs on an embedded application inside the Syrus 4 called SyrusJS which manages a configuration file and all of it's definitions.

Within SyrusJS there's a directory that holds the device's configuration and important files, the location of this directory is also referred to as the application data directory: /data/app_data/<INSTANCE_NAME>/.

The important files to consider within this directory are:

Filename	Description
appends.syrus.conf	Any remote command sent to the device (automatically generated).
configuration.syrus.conf	Device's main configuration file.
destinations.syrus.conf	Device's destination definitions.

Comments within any of the filenames above can be written with # in front of the line with the comment.

# comment
define command
# >!@#% this is another comment

The Syrus Cloud Applications can be used to manage the files within SyrusJS and create your own script.

Configuration access

Via shell you can edit the configuration using an editor like vi or tail logs.

• Logs directory: /data/logs
• Application data: /data/app_data/<INSTANCE_NAME>

Please note that the logs file rotates every hour and if the size is greater than 30KB then it will be compressed. Maximum of 8 log files are created.

The system tool syrus-apps-manager can be used to interact with the application itself (start, stop, restart). Just make sure after you update the configuration to restart the application.

syrus-apps-manager restart syrusjs

Definitions

There are 3 main definitions that control what we call the Smart Event Engine of the device.

1. Signals
2. Actions
3. Events

With these 3 definitions you can create thresholds, and trigger messages to be sent to a destination, or actions to be executed locally on the device. It all starts by creating the definitions.

Units

Unless otherwise specified, Syruslang will follow the basic units of the metric system for time, distance, and speed (seconds, meters, and km/h, respectively).

Create

In order to create a definition you have to start a new line with define followed by the name of the definition you want to create:

define definition custom_name

As you create the definitions you assign a unique custom_name to each one. Be aware that the naming must follow these rules:

• are case-sensitive
• 3 to 25 characters
• cannot start with a number
• only underscore is allowed as a special character _
• cannot be special keywords like: and, or, not, exec, apx, group
• [a-zA-Z_][a-zA-Z0-9_]{2,24}

There is no limit as to how many definitions you can create, but keep in mind that no two definitions can share the same custom_name.

⚠️

Using the same definition and custom_name will overwrite the original definition.

❌ define signal my_signal ... <- original
✅ define signal my_signal ... <- this will overwrite the original

Using a different definition with the same custom_name is not good practice.

✅ define signal custom1
❌ define event custom1

💡

Definitions can also span multiple lines

✅ define signal
	my_signal ...
	more ...
✅ define event
	custom1 ...

Evaluation

The event engine is evaluated in the order mentioned above, first with signals, then the actions and finally the events. This is important because you may have a signal that fires an action that triggers an event, and you need to keep in mind which one is going to trigger first.

Manipulation

Definitions can be deleted with the delete keyword, followed by the definition and its name:

delete definition custom_name

⚠️

Deleting a definition has a cascade effect in terms of what's associated to that definition, thus you have to consider what actions and events are associated to each definition.

Event Engine

The unit's reporting is controlled by an Event Engine which constantly evaluates user definitions. The 3 main definitions are signals, actions, and events.

• Signals: used to evaluate when you want something to happen (i.e. when the input is pressed, or when the speed is above a certain value)
• Actions: used to fire a specific task once a signal is met (i.e. activate an output or make a call)
• Events: used to notify an endpoint once a signal is met (i.e. generate a message to send to the server to indicate that the panic was pressed)

Signals

The main component of Syruslang is the definition of signals.
There are two types of signals:

1. fixed signals - built-in device signals, start with @ symbol
2. custom signals - custom created signals that require an operator and value

To create a signal you have to use the following format (values with [] mean they're optional):

define signal signal_name [min_duration] $device_component [operator] [value]
or
define signal signal_name
	[min_duration] $device_component [operator] [value]

Once defined, a signal can be used to trigger actions, events, or both.

Keep in mind that the signals you create evaluate when the conditions change, in other words, once a signal is defined and its condition becomes true, the signal will not reevaluate or trigger again until it changes from false to true again. So if you have an action or event that depends on a signal that stays true, it will only evaluate 1 time until the signal changes from false to true again.

Signal definition example:

define signal ignitionIsOn min_duration=10sec $io.ign == true

The default operator and value are == and true so the signal definition above can also be rewritten to:

define signal ignitionIsOn 
	min_duration=10sec $io.ign

Breakdown of the signal definition:

min_duration

The minimum duration that the condition (made up of the $device_component, operator, and value) must be met in order for the signal to transition to true. It has the following format, #A where # is any number and A represents the time unit:

• sec - seconds
• min - minutes
• hr - hours

a min_duration=10sec for example, means that the condition must be met for 10 consecutive seconds, before the signal transitions to true.

$device_component

Device components refer to the internal modules and interfaces that the device is capable of interacting with. The device components section has a list of the available signals that can be constructed with each internal module/interface.

$gnss.speed
$net_wifi.ip_address
$net_cell.connected
$accelerometer.motion

operators

The operators supported are:

==  >  <  >=  <=  !=

value

The value varies depending on the field selected, can be bool, string, or a number.

Example of Signal Definitions

define signal ignitionON min_duration=5sec $io.ign
define signal ignitionOFF min_duration=5sec $io.ign == false
define signal speeding min_duration=2sec $gnss.mph > 70
define signal parked min_duration=10sec $accelerometer.motion == false
define signal buzzer $io.out2
define signal siren $io.out3
define signal usa_country_code $net_cell.mcc == 310
define signal att_network_code $net_cell.mnc == 410 
define signal slow
	min_duration=10sec $gnss.kph < 10
define signal work_wifi
	$net_wifi.ip_address == 123.123.123.123

---

Trigger (Signal Combination)

Various signals can be combined to form a combination of several situations that can trigger an event or an action.

The parameter trigger is used to create an equation using signals and logical operators: and, or, not, in a post fixed notation syntax. Post-fixed notation means that the signals are placed first, and the operator is at the end of the signals to be evaluated, the signals and the operators are separated by a comma.

Examples

A or B → A,B,or

A and B → A,B,and

A and B and C → A,B,and,C,and
same as..
A and B and C → A,B,C,and,and

(A and B) or C → A,B,and,C,or

A and (!B or C) → A,B,not,C,or,and

(A and B) or (C and D) → A,B,and,C,D,and,or

thus you can combine the signals defined previously like this:

# idling
ignitionON,parked,and

# attached to AT&T in US
usa_country_code,att_network_code,and

# not moving
ignitionON,parked,slow,or,and,ignitionOFF,or

# parked at the office
ignitionOFF,work_wifi,and

As mentioned above, the signals can be combined in actions and events.

Keep in mind that when you define a trigger for the first time, if all the signals within the trigger are true, the trigger will evaluate and fire.

Next we will look at how to define an action.

---

Actions

Actions can be defined to tell the device what to do when a trigger goes off. They have the following format:

define action action_name [rate] trigger=signal1[,signal2,operator,...] command

💡

Multiple actions can be fired from a single trigger by separating each action with a new line and tab

define action action_name trigger=signal1[,signal2,operator,...]
	command1
	command2

define action ac_my_action trigger=signal1
	set output1 on
	set output2 on
	start recording

rate

Similar to the rates of an event, actions can have their own rates in order to avoid executing excess number of actions. The format for rates is A/Bunit where A is the amount of fires to allow, and Bunit is the time frame to allow it for. The possible units are sec, min, hr.

For example a rate of 1/2hr allows only 1 fire every 2 hours. After the 2 hours complete the rate is reset back to 0 and the unit can fire once more in the span of 2 hours.

💡

This is very useful for actions that have to do with voice alerts, as these can get annoying really quick, unless of course that's your goal

command

The command that can be executed can be found in the device components section, as action use

Action definition example:

define action speedingBuzzer trigger=speeding set output2 on

💡

You can substitute == true and == false for the words on & off respectively

define action enable_hotspot trigger=work_wifi,ignitionOFF,and set output2 on

💡

You can execute any system tool command with the exec keyword.

The command can be a standalone line with the instruction:

exec apx-ethernet off

or part of an action

define action my_action trigger=no_gps exec apx-gps cold-start

Events

Events can be triggered by the same signals as an action and they can be used to notify an endpoint when a condition is met. When an event is triggered it follows this sequence of steps:

1. Creates a message according to the protocol on the events destination definition
2. Appends any additional fields to the payload via the fieldsets
3. Queues the payload on a data buffer (FIFO) per endpoint defined
4. Attempts to communicate with the endpoints in order to remove the payload from its queue
5. Depending on the Acknowldgement configured it either waits for a confirmation from the endpoint or moves on to the next event in queue.
6. If no response from the endpoint is received the messages are retried in increasing timeouts, after 5sec, 10sec, 30sec, 60sec, etc. til it reaches 1min and keeps retrying every 1min.

The event definition format is as follow:

define event event_name group [fieldset] [rate] [ack] [label] [code] [photo] trigger=signal1[,signal2,and,...]

param	description	default value
group	is a way to group several events for destination handling	default
fieldset	refers to the additional information that can be attached to an event besides the location information, we'll look at this in more detail later
rate	refers to a firing limit for this event
ack	refers to the acknowledgement message that's used by an endpoint to handle the correct reception of the event, for mqtt endpoints this is the equivalent of QoS	seq
retain	set to false to disable the retain message flag for mqtt destinations	true
label	refers to a short string, up to 10 characters (alphanumeric, period [.] accepted), that's used to identify the event generated on an endpoint using taip protocol	trckpnt
code	is a numeric code for the event generated (range: 0, 9999), useful for taip protocol messages	0
photo	whether the event will have a photo associated to it	false
trigger	are the signals that we defined earlier that can be combined with logical operators.

Event definition examples:

define event movement group=default fieldset=minimum rate=5/1min ack=disabled label=trckpnt code=1 trigger=moving
define event ignition_on group=tracking fieldset=default ack=seq label=ignon code=2 trigger=ignitionON
define event speeding_70 group=alerts fieldset=important ack=seq label=spd code=3 trigger=speeding
define event parked group=default fieldset=minimum rate=2/1hr ack=disabled label=park code=4 trigger=isON,slow,and,nomov,and

Event Grouping (group)

Groups can be defined in order to get multiple events reporting to the same destination.

The first step is to define a group:

define group group_name

Once defined you can append this group_name to any event and later on apply fieldsets or destinations to that group of events.

To relate the group to a destination use the following command:

set destinations group=group_name destination_name1[,destination_name2]

Example, if we have the following events defined:

define event ignition_is_on group=important ack=seq label=ignon trigger=ignitionON
define event ignition_is_off group=important ack=seq label=ignoff trigger=ignitionOFF
define event panic_and_parked group=important ack=seq label=panic trigger=panic,parked,and
define event speeding_70 group=important ack=seq label=spd trigger=speeding

the first 3 events we can direct towards the main_server and the backup server with:

set destinations group=important main_server,backup

the 4th event falls in the default group so those can be directed to just the main_server for example:

set destinations group=default main_server

Thus, the destination file will depend on the groups of events defined in your configuration.syrus.conf. Note, if an event has no destination set it will simply be discarded.

Fieldset

Fieldsets are data fields that can be appended to the payload of an event.

Start by defining a fieldset

# fieldset definition my_fields
define fieldset my_fields fields=field1,field2,etc..

Then you can use it on any event

# appends my_fields to my_event
define event my_event fieldset=my_fields ...

The fields come from the device components section, look for fieldset use.

To define or transform fieldset values & sets:

VALUES

fields=$battery.voltage

{
	"$battery": {
		"voltage": 4.1
	}
}

fields="foo":$battery.voltage or fields=foo:$battery.voltage

{
	"foo": 4.095
}

fields=foo.bar:$battery.voltage

{
	"foo": {
		"bar": 4.098
	}
}

SETS

fields=$battery

{
	"$battery": {
		"connected": true,
		"voltage": 4.098,
		"mv": 4098,
		"level": 100
	}
}

fields="foo":$battery

{
	"foo.connected": true,
	"foo.voltage": 4.098,
	"foo.mv": 4098,
	"foo.level": 100
}

fields=bar:$battery

{
	"bar": {
		"connected": true,
		"voltage": 4.098,
		"mv": 4098,
		"level": 100
	}
}

fields=foo.bar:$battery

{
	"foo": {
		"bar": {
			"connected": true,
			"voltage": 4.098,
			"mv": 4098,
			"level": 100
		}
	}
}

Example:

fields=position.context.lat:$gnss.latitude,position.context.lng:$gnss.longitude,position.value:$gnss.fix

{
	"position": {
		"context": {
			"lat": 25.783618,
			"lng": -80.293516
		}
	},
	"value": 3
}

For TAIP protocol, you just need to define a csv of all the compatible sets from device components.

Example:

define fieldset taip_pegasus fields=$gnss,$io,$net_cell,$ecu,$accelerometer

SyrusJS will automatically fill those fields with the appropriate subfields for TAIP messages.

Rate

The rates are used to avoid firing an event in excess by limiting the amount of fires an event can have within a period of time. The format for rates is A/Bunit where A is the amount of fires to allow, and Bunit is the time frame to allow it for. The possible units are sec, min, hr.

For example a rate of 5/1min allows only 5 fires of the event in the span of 1 minute. After the minute completes the rates are reset to 0 and the unit can fire 5 times again in the span of 1 min.

💡Tip: This is very useful for events that have to do with physical connections like inputs, analog values, ignition, because these are proned to installation failures which can lead to multiple false fires

Label

Labels are important for TAIP protocol, when sending the data to Pegasus for example. They are used to identify an event. Labels must follow these guidelines:

• 1 to 10 characters
• letters can only be lowercased
• only period . is allowed as a special character
• cannot have consecutive periods
• [a-z0-9.]{1,10}
• can have the same name as a definition

Photo

The photo parameter is used to associate a photo to an event. When a compatible accessory is connected, like a fatigue_sensor, you can associate any photo captured or a specific photo captured with this.

Destinations

Destinations are the the endpoints where the data generated by the device will be reported, they are saved in a separate file called: destinations.syrus.conf within the app directory /data/app_data/syrusjs/

To define a destination:

define destination name protocol transport:endpoint[?args] [allowed_] [ack] [disabled]

name

Name is the custom name given to the destination, can be up to 50 alphanumeric characters.

protocol

The protocol refers to the data format that the payload is transmitted in:

• json
• taip (Syrus 3 and older devices payload for Pegasus platform)

transport

Transport refers to the method of transportation of the data, the following methods are supported:

• mqtt
• tcp
• http/https
• file
• satcom
• bluetooth

MQTT Protocol Support on Syruslang

MQTT 3.1.1	MQTT 5.0	SSL/TLS	TCP	WS/WSS	QoS

Yes    |   Yes    |  Yes    | Yes |  Yes   | 0,1,2

More information about MQTT (opens new window)

endpoint

The endpoint refers to the destination of the data, it can be various formats depending on the transport, for now given the transports defined earlier, the following are supported:

mqtt, tcp, http[s]:

://url[:port]

://ip_address[:port]

file

:///path/to/file.log

satcom, bluetooth

://_:_

Note that you can use variables in the endpoint from the components section by adding it inside two curly brackets {{}}:

Examples:

://url.com/syrus/{{$modem.imei}}

?args

The optional ?args refers to params that can be appended to the endpoint.

• ?ssid=value&pass=pass1

allowed_

The connection to this destination will only be available when the specified network is within range/connectable. Outside of the allowed interfaces the destination will queue all messages until it's available again.

value	description
allowed_ssid	when connected to a specific wireless network ssid
allowed_ip	when connected to a specific ip_address
allowed_interface	when connected to one or many of these network interfaces wifi, eth, cell

Example:

# This connection will only allow messages sent via wifi inteface once it's connected/in range.  Any other interface that's used will queue the messages.
define destination mqtt_broker json mqtt://test.mosquitto.org:1883 protocol="mqtt" subscribe="dev/messagestx" publish="dev/messagestx" allowed_interface=wifi

# This example will only send messages when it's connected via ethernet, cellular network or a specific ssid
define destination server json tcp://test.server.com allowed_interface="eth,cell" ssid="Linksys Home Router"

ack

Configure the message acknowledgement to be used by a destination:

transport	ack supported	details
mqtt	✅	ack supported using QoS
tcp	✅	ack supported via taip protocol
http	🚫	no ack support
https	🚫	no ack support
file	🚫	no ack support
satcom	🚫	no ack support
bluetooth	🚫	no ack support

See the Message Acknowledgement and Queues section for more information on the specific ack configurations.

disabled

Disables the endpoint, this is useful if you want to control it via an action, for Satcom/Sigfox destinations for example.

define destination satcom_destination taip satcom://_:_ ack=disabled disabled=true

The commands to enable and disable the destination are:

enable destination name or disable destination name

and some sample actions:

define action enable_satcom trigger=disconnected enable destination satcom_destination

define action disable_satcom trigger=disconnected,not disable destination satcom_destination

Useful for the satcom destination

MQTT

MQTT can be used as a destination transport method, for a full tutorial that incorporates mqtt checkout this walkthrough. The following parameters are available when creating a destination definition for an MQTT endpoint:

param	description	example
clean	indicate whether or not a persistent session is required (set to false to keep a persistent session)	false
clientId	client identifier	"client-1"
keepalive	keep alive period to maintain a connection open with broker	60
lastWillPayload	message to send when client disconnects ungracefully	"unexpected exit"
lastWillQoS	last will quality of service	1
lastWillRetain	whether or not to retain the last will message	true
lastWillTopic	last will topic	"dev/imei/connect/status"
username	username for client authentication	"user"
password	password for client authentication	"pass"
protocol	used to define the transport method and security, see below for protocol list	"mqtts"
publish	topic to publish event messages	"dev/imei/events"
commands_pub	topic to publish command responses	"dev/imei/commands/resp"
subscribe or commands_sub	topic that handles syruslang commands	"dev/imei/commands"

Note that only one topic to publish event messages can be set per definition, but you can have multiple definitions with different topics.

Other parameters like the QoS & retain of each message are handled in the events definition.

method	port	protocol	secure
mqtt over tcp	1883	mqtt	no
mqtt over tls	8883	mqtts	yes
mqtt websockets	80	ws	no
mqtt websockets over tls	443	wss	yes

Example MQTT endpoints

define destination mqtt_over_tcp json mqtt://mqtt.pegasusgateway.com:1883 protocol="mqtt" publish="dev/{{$modem.imei}}/pub" subscribe="dev/{{$modem.imei}}/sub" commands_pub="dev/{{$modem.imei}}/commands"
define destination mqtt_over_tcp_ssl json mqtt://mqtt.pegasusgateway.com:8883 protocol="mqtts" publish="dev/{{$modem.imei}}/pub" subscribe="dev/{{$modem.imei}}/sub" commands_pub="dev/{{$modem.imei}}/commands"
define destination mqtt_over_ws json mqtt://mqtt.pegasusgateway.com:80 protocol="ws" publish="dev/{{$modem.imei}}/pub" subscribe="dev/{{$modem.imei}}/sub" commands_pub="dev/{{$modem.imei}}/commands"
define destination mqtt_over_wss json mqtt://mqtt.pegasusgateway.com:443 protocol="wss" publish="dev/{{$modem.imei}}/pub" subscribe="dev/{{$modem.imei}}/sub" commands_pub="dev/{{$modem.imei}}/commands"

HTTP(S)

When creating an http endpoint you can use the following notation to append headers: headers.HEADER_NAME=VALUE

# endpoint with application/json content-type
define destination my_endpoint json http://api.mysite.com/devices headers.content-type="application/json"

# endpoint with authorization and content-type
define destination other_endpoint json https://api.mysite.io/devices headers.authorization="Bearer XXXXXXXXX" headers.content-type="application/json"

Message acknowledgement and queues

Once an event is generated the device stores it in a queue per endpoint that the event is sent to. Any event in queue is transmitted to the endpoint every second as long as a connection is established.

If the endpoint requires internet connection, there's 3 possibilities to reach it:

1. Ethernet
2. Wi-Fi
3. Cellular (4G/LTE)

The data traffic by default is sent in that order of priority, with Ethernet being the preferred method.

By default SyrusJS uses the TCP stack to guarentee message delivery, however under special circumstances it's recommended to implement an application level ACK, this is where the ack param comes in.

The ack param of the event verifies if Syrus is expecting any sort of response from the endpoint indicating that it received the event.

protocol & transport	ack	format of ACK Syrus expects	example
taip over tcp	disabled	none
taip over tcp	imei	15 digit modem's IMEI	867698040023056
taip over tcp	seq	>SAK;1,#,0,0< where # is the sequential number generated by Syrus	>SAK;1,1234,0,0

for MQTT the ack controls the QoS and retain flags of the MQTT specification

protocol & transport	ack	QoS	retain
json over mqtt	disabled	0	false
json over mqtt	seq	2	true

---

Maximum queue size

SyrusJS uses Redis and the device's filesystem to store event messages that have not been transmitted to an endpoint. The maximum number of possible messages stored is equivalent to the amount of memory available in the user's storage partition, this partition is roughly 2.2GB and can be monitored in the Syrus 4 UI system page, divided by the size of the messages. Typical message sizes for TAIP can vary between 50 bytes to 500 bytes depending on the accessory, while MQTT can vary from a few bytes up to 5KB.

Logging data to a file

A destination can also be a path to a file, this can be used to log data in any of the protocols defined above. An example endpoint definition is:

file:///path/to/file/out.log

Note: if the file does not exist a new one is created, but if the file does exist already it will be overwritten!

With this example the file is stored in the application's data folder, so you can even view this from the Management Tool's application manager.

define destination logger json file:///data/app_data/syrusjs/output.log

Remote interaction

Depending on the protocol and transport of the destination you defined, you can interact with the device remotely.

If you are using JSON over MQTT you can publish commands to a topic from your remote message broker on your destination definition.

By default SyrusJS will be connected to the topic defined by the params subscribe or commands_sub using QoS = 1.

Once a message (command) is received SyrusJS will publish to the topic commands_pub using QoS = 1 and retain = true.

Thus, to send commands remotely to the Syrus over MQTT you can publish messages to the commands_sub topic.

You can send an action, define something, or retrieve data remotely.

# activate output 2
set out2 on
OK

# define a new definition
define signal signal_name ...
OK

# get a list of all signals
get signals
define signal ignOn $io.ign == true, define signal isIdle ...

💡

Note that any definition that you configure remotely to the device will be appended to a file called appends.syrus.conf on the application's data folder

Commands to retrieve data, definitions, or values

definitions	description
get action custom_name	returns action definition of custom_name
get actions	returns all action definitions
get counter custom_name	returns counter definition of custom_name
get counters	returns all counters definitions
get destination_state custom_name	returns enable if destination is used
get destination custom_name	returns destination definition of custom_name
get destinations	returns all destinations definitions
get event custom_name	returns event definition of custom_name
get events	returns all events definitions
get fieldset custom_name	returns fieldset definition of custom_name
get fieldsets	returns all fieldsets definitions
get geofence custom_name	returns geofence definition of custom_name
get geofences	returns all geofences definitions
get group custom_name	returns group definition of custom_name
get groups	returns all groups definitions
get signal custom_name	returns signal definition of custom_name
get signals	returns all signals definitions
get value $device.component	returns the value of the device component

Note that if you're using the TAIP protocol, you'll need to encapsulate the message within the SL (SyrusLang) command: >SSLmessage<, the response will have the following format: >RSLresponse<

Examples:

# Get fieldset definition
>SSLget fieldset default<
>RSLdefine fieldset default fields="device_id":$modem.imei,"latitude":$gnss.latitude,"longitude":$gnss.longitude,"direction":$gnss.heading,"hdop":$gnss.hdop,"pdop":$gnss.pdop,"vdop":$gnss.vdop,"mph":$gnss.mph,"io_in1":$io.in1,"io_in2":$io.in2,"io_in3":$io.in3,"io_out1":$io.out1,"io_out2":$io.out2,"io_ign":$io.ign,"io_pwr":$io.pwr<

# Get signal value
>SSLget value $net_wifi.ip_address<
>RSL192.168.1.205<

# Action enable hotspot
>SSLenable hotspot<
>RSLOK<

Signals, Actions, and Fieldsets

accelerometer

Accelerometer related information

property	use	type	description
$accelerometer	fieldset	Object	json appends all accelerometer fields
$accelerometer	fieldset	String	taip compatible field
@accelerometer.backward_collision.signal	signal	Boolean	True when detected
@accelerometer.cornering_left.signal	signal	Boolean	True when detected
@accelerometer.cornering_right.signal	signal	Boolean	True when detected
@accelerometer.forward_collision.signal	signal	Boolean	True when detected
@accelerometer.hard_braking.signal	signal	Boolean	True when detected
@accelerometer.harsh_fwd_acceleration.signal	signal	Boolean	True when detected
@accelerometer.lat_collision_from_left.signal	signal	Boolean	True when detected
@accelerometer.lat_collision_from_right.signal	signal	Boolean	True when detected
@accelerometer.motion.signal	signal	Boolean	True when detected
$accelerometer.backward_collision.time	fieldset	String	Time of event
$accelerometer.backward_collision.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.cornering_left.time	fieldset	String	Time of event
$accelerometer.cornering_left.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.cornering_right.time	fieldset	String	Time of event
$accelerometer.cornering_right.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.forward_collision.time	fieldset	String	Time of event
$accelerometer.forward_collision.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.hard_braking.time	fieldset	String	Time of event
$accelerometer.hard_braking.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.harsh_fwd_acceleration.time	fieldset	String	Time of event
$accelerometer.harsh_fwd_acceleration.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.lat_collision_from_left.time	fieldset	String	Time of event
$accelerometer.lat_collision_from_left.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.lat_collision_from_right.time	fieldset	String	Time of event
$accelerometer.lat_collision_from_right.value	fieldset, signal	Number	Acceleration force in milli-g
$accelerometer.motion	fieldset, signal	Boolean	Appends the motion state
$accelerometer.time	fieldset, signal	Boolean	Time of motion event
$accelerometer.value	fieldset, signal	Boolean	Acceleration force in milli-g
set accelerometer self_alignment	action		Executes the self alignment

actions

Actions related info.

property	use	description
trigger action action_name	action	Force the execution of an action

adas (ecu)

ADAS accessory related info, configured via the ecu monitor.

property	use	type	description
$ecu.adas_speed	signal	Number	Speed detected by adas accessory in km/h
$ecu.brakes_enabled	signal	Boolean	True if brakes detected
$ecu.distance_from_front_vehicle	signal	Number	Distance from front vehicle in meters
$ecu.failsafe	signal	Boolean	True if adas triggers one of the internal FailSafe modes, more info
$ecu.forward_collision_warning	signal	Boolean	True if forward collision warning detected
$ecu.headway_measurement	signal	Number	Headway measurement. Unit 0.1s. Range (0 - 9.9s)
$ecu.headway_valid	signal	Boolean	True when CIPV (close in path vehicle) is detected
$ecu.headway_warning_level	signal	Number	Headway warning level, more info
$ecu.headway_warning_repeatable_enabled	signal	Boolean	True when Headway Warning repeatable feature is ON
$ecu.high_beam_signal	signal	Boolean	True if high beam signal detected
$ecu.lane_departure_warning_disabled	signal	Boolean	True if lane departure warning is disabled
$ecu.left_lane_departure_warning	signal	Boolean	True if left lane departure warning detected
$ecu.left_signal	signal	Boolean	True if left signal is detected
$ecu.low_beam_signal	signal	Boolean	True if low beam signal detected
$ecu.maintenance	signal	Boolean	True if adas accessory is maintenance mode
$ecu.pedestrian_danger_zone	signal	Boolean	True if pedestrian in danger zone is detected
$ecu.pedestrian_forward_collision_warning	signal	Boolean	True if pedestrian forward collision warning is detected
$ecu.relative_speed_from_front_vehicle	signal	Boolean	True if relative speed from front vehicle is detected
$ecu.right_lane_departure_warning	signal	Boolean	True if right lane departure warning is detected
$ecu.right_signal	signal	Boolean	True if right signal is detected
$ecu.sound_type	signal	Number	Sound type, more info
$ecu.speed_available	signal	Boolean	True if speed is available
$ecu.speed_limit_recognition_sensitivity	signal	Number	Speed limit recognition sensitivity
$ecu.speed_limit_recognition_state	signal	Number	Speed limit recognition state
$ecu.speed_limit_recognition_value	signal	Number	Speed limit recognition value
$ecu.tamper_alert	signal	Boolean	True if a tamper alert is detected
$ecu.time_indicator	signal	Number	Time indicator, more info
$ecu.traffic_signs_recognition_enabled	signal	Boolean	True when traffic signal recognition feature is on
$ecu.traffic_signs_recognition_warning_level	signal	Number	Traffic signs recognition warning level, more info
$ecu.wipers_signal	signal	Boolean	True when a wiper passes the windshield, 0 if wipers are static
$ecu.zero_speed	signal	Boolean	True if zero speed is detected (vehicle is stopped)

bluetooth

Bluetooth functionality. To speak via the bluetooth check out the modem speak action.

property	use	description
bluetooth connect 'AABBCCDDEEFF'	action	Connect to bluetooth device
bluetooth disconnect 'AABBCCDDEEFF'	action	Disconnect from bluetooth device
bluetooth pair 'AABBCCDDEEFF'	action	Pair to a bluetooth device
bluetooth pair_forced 'AABBCCDDEEFF'	action	Force pairing
bluetooth reset 'AABBCCDDEEFF'	action	🛑 Resets bluetooth paired devices
bluetooth restart 'AABBCCDDEEFF'	action	Restart bluetooth
bluetooth scan seconds	action	Replace with amount of seconds
bluetooth switch_audio 'AABBCCDDEEFF'	action	Switch main audio
bluetooth unpair 'AABBCCDDEEFF'	action	Unpair from bluetooth device
@bluetooth.button.call_2x	signal	Bluetooth call button pressed 2 times
@bluetooth.button.volume_up	signal	Bluetooth volume up
@bluetooth.button.volume_down	signal	Bluetooth volume down
@bluetooth.button.mute	signal	Bluetooth mute button pressed

battery

Device internal battery information.

property	use	type	description
$battery	fieldset	Object	json appends all battery fields
$battery	fieldset	String	taip compatible field
$battery.connected	fieldset,signal	Boolean	True if the internal battery is connected
@battery.critical	signal	Number	Battery <= 10%
@battery.low	signal	Number	Battery <= 20%
@battery.full	signal	Number	Battery = 100%
$battery.mv	fieldset,signal	Number	Internal battery voltage in milliVolts
$battery.level	fieldset,signal	Number	Internal battery level (%)
$battery.voltage	fieldset,signal	Number	Internal battery voltage

counters

Device counters information.

property	use	type	description
$counters	fieldset	Object	json appends all counter fields
$counters	fieldset	String	taip compatible field
$counters.name.odometer	fieldset, signal	Number	Total distance traveled with ignition ON (meters)
$counters.name.ignition_time	fieldset, signal	Number	Total ignition time (seconds)
$counters.name.idle_time	fieldset, signal	Number	Total time spent in idling (seconds)
$counters.name.over_speed	fieldset, signal	Number	Total time spent over speed (seconds)
$counters.name.over_rpm	fieldset, signal	Number	Total time spent over RPMs (seconds)
$counters.name.hard_brakes	fieldset, signal	Number	Total amount of hard brake events (count)
$counters.name.harsh_fwd_acceleration	fieldset, signal	Number	Total amount of harsh forward acceleration events (count)
define counters name	action		Create a counter definition
get counters name	action		Get a counter definition
set counters name field=value	action		Set counter threshold

destinations

Destinations related actions.

property	use	description
enable destination destination_name	action	Enable the destination
disable destination destination_name	action	Disable the destination

ecu

Engine Control Unit related information. For more info visit: Engine Control Unit (ECU).

property	Use	type	description
$ecu	fieldset	Object	json appends all valid ecu parameters
$ecu	fieldset	String	taip compatible fieldset
$ecu.id	fieldset, signal	Multiple	id refers to the specific pgn + start_position
$ecu.param_name	fieldset, signal	Multiple	param_name refers to the parameters listed in the SDK ECU.d directory (opens new window) files
$ecu.error_codes.spn	fieldset, signal	Number	ECU diagnostic trouble code SPN number. More info
$ecu.error_codes.fmi	fieldset, signal	Number	ECU diagnostic trouble code FMI number. More info

events

Events related actions.

property	use	description
send event event_name	action	Generate an event to the defined destinations
fire signal signal_name	action	Simulate a signal

fatigue_sensor

Fatigue sensor accessory related information. Note that the fatigue sensor information can come from either the CAN bus or Serial (RS-232) cables.

property	use	type	description
$fatigue_sensor	fieldset	Object	Akmppends relevant fatigue_sensor information to the payload
@serial.fatigue_sensor.SIGNAL	signal	Boolean	Serial fatigue sensor specific signals
@fatigue_sensor.fatigue_remind	signal	Boolean	True when a fatigue reminder was detected
@fatigue_sensor.fatigue_warning	signal	Boolean	True when yawning or a fatigue warning was detected
@fatigue_sensor.fatigue_alarm	signal	Boolean	True when drowsiness or fatigue alert was detected
@fatigue_sensor.no_portrait	signal	Boolean	True when no driver is detected
@fatigue_sensor.distraction	signal	Boolean	True when the driver is distracted
@fatigue_sensor.phone	signal	Boolean	True when a driver is on their phone
@fatigue_sensor.smoking	signal	Boolean	True when a driver is smoking
@fatigue_sensor.camera_blocked	signal	Boolean	True when the fatigue sensor's camera is blocked
@fatigue_sensor.photo	signal	Boolean	True when a photo was captured manually
@fatigue_sensor.signal	signal	Boolean	True when any fatigue sensor event is triggered
$fatigue_sensor.connected	signal fieldset	Boolean	True if fatigue sensor is connected
$fatigue_sensor.state	signal fieldset	String	"connected" or "disconnected"
$fatigue_sensor.sensitivity	signal fieldset	Number	Sensitivity of the fatigue sensor
$fatigue_sensor.speaker_volume	signal fieldset	Number	Volume of the fatigue sensor
$fatigue_sensor.min_speed	signal fieldset	Number	Minimum speed to trigger fatigue sensor alerts
$fatigue_sensor.speeding	signal fieldset	Number	Speeding threshold
$fatigue_sensor.max_photos	signal fieldset	Number	Total number of photos that can be captured
$fatigue_sensor.nbr_photos	signal fieldset	Number	Number of photos captured
$fatigue_sensor.latest_photo	signal fieldset	Number	Latest photo
$ecu.distraction	signal fieldset	Boolean	True when the driver is distracted
$ecu.yawning	signal fieldset	Boolean	True if the driver is yawning
$ecu.drowsiness	signal fieldset	Boolean	True when drowsiness was detected
$ecu.phone	signal fieldset	Boolean	True if the driver is on their phone
$ecu.smoking	signal fieldset	Boolean	True when smoking was detected by the driver
$ecu.driver_absence	signal fieldset	Boolean	True when there's no driver present
$ecu.camera_blocked	signal fieldset	Boolean	True if the camera is blocked
$ecu.camera_error	signal fieldset	Boolean	True when a camera error was detected
$ecu.zero_speed	signal fieldset	Boolean	True when the vehicle is parked
$ecu.error_valid	signal fieldset	Boolean	True when an error was detected by the fatigue sensor
$ecu.tamper_alert	signal fieldset	Boolean	True if tampering is detected by the fatigue sensor
capture fatigue_sensor photo	action		Captures a photo with the fatigue sensor camera
upload fatigue_sensor photos	action		Manually upload all photos to an ftp destination
set fatigue_sensor sensitivity	action		Change sensitivity (Range: 2-11)
set fatigue_sensor speaker_volume	action		Change the speaker volume (Range: 0-2)
set fatigue_sensor minimum_speed	action		Change the minimum speed to trigger fatigue alerts (Range: 0-254)kph
set fatigue_sensor speeding_alarm	action		Change the speeding alarm (Range: 0-255)kph
set fatigue_sensor buffer_size	action		Change the max photos that can be captured (Range: 10-100)
set fatigue_sensor autoupload	action		Manage the auto upload of photos to the DCT ftp directory, default is 0
clear fatigue_sensor buffer	action		Deletes all photos in the fatigue_sensor directory

geofences

Geofences related information

property	use	type	description
$geofences.name.inside	fieldset, signal	Boolean	Inside <name>
$geofences.name.time	fieldset, signal	Number	Time when device entered <name>
$geofences.$groups.group_name.inside	signal	Boolean	Inside any fence in <group_name>
$geofences.$groups.group_name.outside	signal	Boolean	Outside all fences in <group_name>
@last_geofence.name	fieldset	String	Last geofence name
@last_geofence.state	fieldset	String	inside, outside
@last_geofence.time	fieldset	Number	Time of last geofence

gnss

GNSS position information

property	use	type	description
$gnss	fieldset	Object	json appends all gnss fields
$gnss	fieldset	String	taip compatible fieldset
$gnss.accuracy	fieldset, signal	Number	Position accuracy in meters
$gnss.altitude	fieldset, signal	Number	Altitude AMSL
$gnss.altitudeAccuracy	fieldset, signal	Number	Altitude accuracy
$gnss.bearing	fieldset, signal	Number	Relative bearing to a base station
$gnss.criteria	fieldset, signal	String	GNSS criteria
$gnss.fix	fieldset, signal	Number	1: no fix, 2: 2D fix, 3: 3D fix
$gnss.hdop	fieldset, signal	Number	Horizontal DOP (opens new window)
$gnss.heading	fieldset, signal	Number	Heading 0°N, 90°E, ...
$gnss.kph	fieldset, signal	Number	Speed in kph (float)
$gnss.latitude	fieldset, signal	Number	WGS84 Latitude
$gnss.longitude	fieldset, signal	Number	WGS84 Longitude
$gnss.mph	fieldset, signal	Number	Speed in mph (float)
$gnss.pdop	fieldset, signal	Number	Position DOP (opens new window)
$gnss.satsActive	fieldset, signal	Number	Satellites used
$gnss.speed	fieldset, signal	Number	Speed value in m/s (float)
$gnss.timestamp	fieldset, signal	Number	Epoch gps timestamp
$gnss.vdop	fieldset, signal	Number	Vertical DOP (opens new window)
$kph	fieldset, signal	Number	Speed in kph (integer)
$mph	fieldset, signal	Number	Speed in mph (integer)
$speed	fieldset, signal	Number	Speed value in m/s (integer)
$timestamp	fieldset	String	dddd, MMMM D, YYYY h:hh A format (opens new window)
$timestamp.es	fieldset	String	dddd, D de MMMM de YYYY HH:hh format (opens new window)
$timestamp.fr	fieldset	String	dddd D MMMM YYYY HH:hh format (opens new window)
$timestamp.pt	fieldset	String	dddd, D de MMMM de YYYY HH:hh format (opens new window)
set gnss hot-start	action		Executes a gps hot start
set gnss warm-start	action		Executes a gps warm start
set gnss cold-start	action		Executes a gps cold start

ibutton

IButton component, note that a total of 500 onewire devices can be created (between ibutton and temperature sensors)

property	Use	type	description
$ibutton	fieldset	Object	json appends all ibutton fields
IB:$ibutton.connected.id	fieldset	String	taip connected ibutton id
IS:$ibutton.last.id	fieldset	String	taip last connected ibutton id
$ibutton.authorized.connected.alias	fieldset, signal	String	Alias of authorized ibutton
$ibutton.authorized.connected.id	fieldset, signal	String	ID of the authorized ibutton
$ibutton.authorized.connected.conn_epoch	fieldset, signal	Number	Epoch of when it was connected
$ibutton.authorized.last.alias	fieldset, signal	String	Alias of last authorized ibutton
$ibutton.authorized.last.id	fieldset, signal	String	Current ID of the last authorized ibutton
$ibutton.authorized.last.conn_epoch	fieldset, signal	Number	Epoch of last authorized ibutton connection
$ibutton.authorized.last.disc_epoch	fieldset, signal	Number	Epoch of last authorized ibutton disconnection
$ibutton.connected	fieldset, signal	Boolean	True if IButton is connected
$ibutton.connected.alias	fieldset, signal	String	Alias of connected ibutton
$ibutton.connected.id	fieldset, signal	String	ID of the connected ibutton
$ibutton.connected.whitelisted	fieldset, signal	Boolean	True if ibutton connected is authorized
$ibutton.connected.conn_epoch	fieldset, signal	Number	Epoch of ibutton connection
$ibutton.last.alias	fieldset, signal	String	Alias of last connected ibutton
$ibutton.last.id	fieldset, signal	String	ID of last connected ibutton
$ibutton.last.whitelisted	fieldset, signal	Boolean	True if last ibutton is authorized
$ibutton.last.conn_epoch	fieldset, signal	Number	Epoch of last ibutton connection
$ibutton.last.disc_epoch	fieldset, signal	Number	Epoch of last ibutton disconnection
add ibutton alias_name id	action		add ibutton to authorized list
remove ibutton alias_name	action		remove ibutton from authorized list by alias_name
remove ibutton id	action		remove ibutton from authorized list by id
remove ibuttons	action		🛑 remove all ibuttons from authorized list
get ibutton alias_name	action		get ibutton by alias_name
get ibutton id	action		get ibutton by id
get ibuttons	action		get list of ibutton defined

io

Inputs/Outputs component

property	Use	type	description
$io	fieldset	Object	json appends all io fields
$io	fieldset	String	taip compatible fieldset
$io.an1	fieldset, signal	Number	Analog input channel 1 (range: 0-28000mV)
$io.an2	fieldset, signal	Number	Analog input channel 2 (range: 0-28000mV)
$io.dan	fieldset, signal	Number	Differential analog values (range: 0-10000mV)
$io.ign	fieldset, signal	Boolean	True when the state of the ignition is ON
$io.in1	fieldset, signal	Boolean	True when input 1 is ON
$io.in2	fieldset, signal	Boolean	True when input 2 is ON
$io.in3	fieldset, signal	Boolean	True when input 3 is ON
$io.in4	fieldset, signal	Boolean	True when input 4 is ON
$io.in5	fieldset, signal	Boolean	True when input 5 is ON
$io.in6	fieldset, signal	Boolean	True when input 6 is ON
$io.in7	fieldset, signal	Boolean	True when input 7 is ON
$io.out1	fieldset, signal	Boolean	True when output 1 is ON
$io.out2	fieldset, signal	Boolean	True when output 2 is ON
$io.out3	fieldset, signal	Boolean	True when output 3 is ON
$io.out4	fieldset, signal	Boolean	True when output 4 is ON
$io.pwr	fieldset, signal	Boolean	True when external power is ON
$io.so1	fieldset, signal	Boolean	True when a short circuit on output 1 is detected
$io.so2	fieldset, signal	Boolean	True when a short circuit on output 2 is detected
$io.so3	fieldset, signal	Boolean	True when a short circuit on output 3 is detected
$io.so4	fieldset, signal	Boolean	True when a short circuit on output 4 is detected
$io.tig	fieldset, signal	Boolean	True when ignition detected from power
set output# on	action		activate output #
set output# off	action		deactivate output #

mdt

RS-232 Mobile Data Terminal info

property	use	type	description
$mdt	fieldset	Object	json appends mdt information
@mdt.message	signal	String	True whenever an incoming message is received via MDT mode
set mdt	action		Set MDT settings
send mdt message	action		Send MDT message

modem

Modem information.

property	use	type	description
$modem	fieldset	Object	json appends all modem fields
$modem	fieldset	String	taip compatible fieldset (includes ;SC tag)
$modem.band	fieldset, signal	String	LTE band
$modem.cid	fieldset, signal	String	Cell ID in hex format
$modem.esim_id	fieldset, signal	String	Embedded sim ID
$modem.esim_imsi	fieldset, signal	String	Embedded sim IMSI
$modem.esim_state	fieldset, signal	String	Embedded sim card state ("READY", "Not in Use")
$modem.gprs_reg	fieldset, signal	Number	GPRS registration status
$modem.gsm_reg	fieldset, signal	Number	GSM registration status
$modem.imei	fieldset, signal	Number	Unique numeric identifier
$modem.ip	fieldset, signal	String	IP address assigned by operator
$modem.lac	fieldset, signal	Number	Location area code
$modem.manufacturer	fieldset, signal	String	Modem's manufacturer
$modem.mcc_mnc	fieldset, signal	Number	Mobile Country and Network Code
$modem.model	fieldset, signal	String	Model of modem
$modem.modem_state	fieldset, signal	String	State of the modem ("ON", "OFF")
$modem.no_conn_time	fieldset, signal	String	Time spent with no connection in minutes, note that this is exclusively for the modem, so the device could be connected via ethernet/wifi and not LTE
$modem.operator	fieldset, signal	String	Network operator
$modem.rat	fieldset, signal	String	Radio access technology
$modem.revision	fieldset, signal	String	Modem's revision
$modem.rssi	fieldset, signal	Number	Received Signal Strength Indicator (0-32)
$modem.sim_id	fieldset, signal	Number	External sim ID
$modem.sim_imsi	fieldset, signal	Number	External sim IMSI
$modem.sim_state	fieldset, signal	Number	External sim State ("READY", "Not in Use")
$modem.sim_type	fieldset, signal	Number	SIM Type ("EMBEDDED" / "EXTERNAL")
set airplane_mode true	action		Set to true to enable airplane_mode
set sim_switch_interval 8	action		Time interval in hours to wait to switch from external to internal sim card
start call +1234567890	action		Start a phone call
end call	action		End a phone call
send sms 3013333333 'testing sms'	action		Send an SMS message to 3013333333
add phone +1234567890	action		Add phone +1234567890 to phonebook
remove phone +1234567890	action		Remove phone +1234567890 from phonebook
set call_validation true	action		Enable call validation from phonebook
set sms_validation true	action		Enable call validation from phonebook
speak lang=en 'hello world'	action		Speak via the bluetooth

net_cell

Cellular interface

property	use	type	description
$net_cell.connected	fieldset, signal	Boolean	True when connected
$net_cell.iccid	fieldset, signal	Number	SIM card ICCID
$net_cell.imei	fieldset, signal	Number	Device unique IMEI number
$net_cell.imsi	fieldset, signal	Number	SIM card IMSI
$net_cell.ip_address	fieldset, signal	String	IP assigned by MNO
$net_cell.mcc	fieldset, signal	Number	Mobile country code
$net_cell.mnc	fieldset, signal	Number	Mobile network code
$net_cell.operator	fieldset, signal	String	Network operator
$net_cell.rx_bytes	fieldset, signal	Number	Bytes received
$net_cell.tx_bytes	fieldset, signal	Number	Bytes transmitted

net_eth

Ethernet interface

property	use	type	description
$net_eth.connected	fieldset, signal	Boolean	Ethernet connected
$net_eth.ip_address	fieldset, signal	String	IP address
$net_eth.rx_bytes	fieldset, signal	Number	Bytes received
$net_eth.tx_bytes	fieldset, signal	Number	Bytes transmitted
enable ethernet	action		Enables the ethernet interface
disable ethernet	action		Disables the ethernet interface

net_wifi

Wifi interface

property	use	type	description
$net_wifi.connected	fieldset, signal	Boolean	WiFi connected
$net_wifi.ip_address	fieldset, signal	String	IP address
$net_wifi.key_mgmt	fieldset, signal	String	Key management protocol
$net_wifi.mac	fieldset, signal	String	WiFi MAC address
$net_wifi.rx_bytes	fieldset, signal	Number	Bytes received
$net_wifi.signal	fieldset, signal	Number	Signal strength in dbm
$net_wifi.ssid	fieldset, signal	String	SSID name
$net_wifi.state	fieldset, signal	String	Wifi connection ("Completed", "Disabled", "Interface_disabled" (when hotspot is on))
$net_wifi.tx_bytes	fieldset, signal	Number	Bytes transmitted
enable wifi	action		Enables the wifi interface
disable wifi	action		Disables the wifi interface
restart wifi	action		Restarts the wifi interface

net_wlan1 (hotspot)

Hotspot interface

property	use	type	description
$net_wlan1.connected	fieldset, signal	Boolean	Hotspot connected
$net_wlan1.ip_address	fieldset, signal	String	IP address
$net_wlan1.rx_bytes	fieldset, signal	Number	Bytes received
$net_wlan1.tx_bytes	fieldset, signal	Number	Bytes transmitted
enable hotspot	action		Enables the hotspot
disable hotspot	action		Disables the hotspot

power_save

Power save mode

property	use	type	description
@power_save.ign	signal	Boolean	Wake up by ignition
@power_save.in1	signal	Boolean	Wake up from input 1
@power_save.in2	signal	Boolean	Wake up from input 2
@power_save.in3	signal	Boolean	Wake up from input 3
@power_save.in4	signal	Boolean	Wake up from input 4
@power_save.in5	signal	Boolean	Wake up from input 5
@power_save.in6	signal	Boolean	Wake up from input 6
@power_save.in7	signal	Boolean	Wake up from input 7
@power_save.motion	signal	Boolean	Wake up from motion
@power_save.pwr	signal	Boolean	Wake up from ext power
@power_save.sleep	signal	Boolean	Entering power save
@power_save.so1	signal	Boolean	Wake up from short circuit on out1
@power_save.so2	signal	Boolean	Wake up from short circuit on out2
@power_save.so3	signal	Boolean	Wake up from short circuit on out3
@power_save.so4	signal	Boolean	Wake up from short circuit on out4
@power_save.tig	signal	Boolean	Wake up from ignition on power
@power_save.time	signal	Boolean	Wake up by time
@power_save.wakeup	signal	Boolean	Wakes up from power save
$power_save.mode	fieldset	String	Power save mode string
$power_save.reason	fieldset	String	Wake up reason
$power_save.status	fieldset	Boolean	Power save mode status
set power_save immediate	action		Force start power save mode
set power_save mode [PSM_STRING]	action		Modify power save mode

satellite (satcom/sigfox)

property	Use	type	description
$satcom	fieldset	Object	json appends all timer fields
$satcom	fieldset	String	taip appends satellite modem's information
$satcom.state	signal	String	State is connected when satellite is connected
$satcom.id	signal	String	Satellite modem's id (imei)
$satcom.signal	signal	Number	Signal strength, 0: weakest, 5: strongest
$satcom.buff_size	signal	Number	Maximum allowed messages to be stored
$satcom.buff_count	signal	Number	Amount of messages stored
enable destination destination_name	action		Enables a destination
disable destination destination_name	action		Disables a destination

timers

property	Use	type	description
$timers	fieldset	Object	json appends all timer fields
@timers.timer_name	signal	Boolean	True if timer timer_name reaches its duration
start timer timer_name	action		Start a timer
stop timer timer_name	action		Stops and clears a timer
enable timer timer_name	action		Enables a timer
disable timer timer_name	action		Disables a timer

temperature

Temperature component, note that a total of 500 onewire devices can be created (between temperature sensors and ibuttons)

property	Use	type	description
$temp	fieldset	Object	json appends all temp fields
$temp.aliases	fieldset	Object	json Temperature info for all sensors
$temp.aliases.alias_name	fieldset	Object	json Temperature info for particular alias
$temp.sensor_list	fieldset	Object	json Temperature value for all sensors
$temp.sensor_list.n	fieldset	Object	json Temperature value for nth index
EA_[A|B|C]:$temp.aliases.alias_name.value	fieldset	Number	taip Temperature value for alias_name
EA_[A|B|C]:$temp.sensor_list.n.value	fieldset	Number	taip Temperature value for nth index
$temp.aliases.alias_name.id	fieldset, signal	String	ID of temperature sensor alias_name
$temp.aliases.alias_name.value	fieldset, signal	Number	Temperature value in °C
$temp.aliases.alias_name.connected	fieldset, signal	Boolean	True if alias_name is connected
$temp.aliases.alias_name.epoch	fieldset, signal	Number	Timestamp of temperature sensor alias_name reading
$temp.sensor_list.n.id	fieldset, signal	String	ID of nth temperature sensor
$temp.sensor_list.n.value	fieldset, signal	Number	Temperature value in °C
$temp.sensor_list.n.connected	fieldset, signal	Boolean	True if nth sensor is connected
$temp.sensor_list.n.epoch	fieldset, signal	Number	Timestamp of nth temperature sensor reading
add temperature_sensor alias_name id	action		add temperature sensor
remove temperature_sensor alias_name	action		remove temperature sensor by alias_name
remove temperature_sensor id	action		remove temperature sensor by id
remove temperature_sensors	action		🛑 remove all temperature sensors defined
get temperature_sensor alias_name	action		get temperature sensor by alias_name
get temperature_sensor id	action		get temperature sensor by id
get temperature_sensors	action		get list of temperature sensors defined
get temperature	action		get last temperature

tpms (ecu)

TPMS information from the engine control unit.

property	Use	type	description
$ecu	fieldset	Object	json appends all valid ecu data including tpms data
$tpms	fieldset	Object	json appends all the tpms fields according to each alert reported
$ecu	fieldset	String	taip compatible fieldset
$ecu.id	fieldset, signal	Multiple	id refers to the specific pgn + start_position
$ecu.param_name	fieldset, signal	Multiple	param_name refers to the parameters listed in the SDK ECU.d directory (opens new window) files
$ecu.$tires.axle_index_X.tire_Y.pressure	fieldset, signal	Number	Pressure in kPa for a specific tire where X refers to the axle index (starts at 0), and Y refers to the tire index
$ecu.$tires.axle_X.tire_Y.pressure	fieldset, signal	Number	Pressure in kPa for a specific tire where X refers to the axle index (starts at 1), and Y refers to the tire index
$ecu.$tires.axle_index_X.tire_Y.temperature	fieldset, signal	Number	Temperature in °C for a specific tire where X refers to the axle index (starts at 0), and Y refers to the tire index
$ecu.$tires.axle_X.tire_Y.temperature	fieldset, signal	Number	Temperature in °C for a specific tire where X refers to the axle index (starts at 1), and Y refers to the tire index
@tpms.alarm_ok	signal	Boolean	True when there's no tpms alerts/alarms detected
@tpms.sensor_mute	signal	Boolean	True when any tire reports a missing signal
@tpms.sensor_defective	signal	Boolean	True if any tire reports a defective sensor
@tpms.tire_leak	signal	Boolean	True if any tire reports a tire leak
@tpms.temperature_warning	signal	Boolean	True if a tire reports a temperature warning
@tpms.over_inflation_critical	signal	Boolean	True if a tire reports a critical over inflation
@tpms.over_inflation_warning	signal	Boolean	True if a tire reports a warning over inflation
@tpms.under_inflation_critical	signal	Boolean	True if a tire reports a critical under inflation
@tpms.under_inflation_warning	signal	Boolean	True if a tire reports a warning under inflation

tracking_resolution

Tracking resolution information

property	use	type	description
@tracking_resolution.name.distance	signal	Boolean	Distance is met
@tracking_resolution.name.heading	signal	Boolean	Heading is met
@tracking_resolution.name.time	signal	Boolean	Time is met
@tracking_resolution.name.signal	signal	Boolean	Any criteria is met
set tracking_resolution name degrees time distance	action		Modify a tracking resolution

variables

Variables related information

property	use	type	description
$variables	fieldset	Object	json appends all valid ecu data including tpms data
$variables.name	fieldset, signal	String	Contents of the variable name
set variable name	action		Set variable name to something

video

Video related information, more info

property	use	type	description
start recording	action		Starts a video recording
stop recording	action		Stops a video recording
create video	action		Creates a video clip

Features

Accelerometer

Actions and Signals List

The accelerometer allows you to configure the signals related to driving including collision and aggressive driving behavior. To get accurate results you must first calibrate the accelerometer once the device is properly installed in a vehicle, you can visit the management tool section for more info.

Set

You can calibrate the accelerometer with the following command

set accelerometer self_alignment

and set individual thresholds with

set accelerometer CFG_FORWARD_COLLISION -2500
set accelerometer CFG_BACKWARD_COLLISION 2150
set accelerometer CFG_LAT_COLLISION_FROM_RIGHT -1930
set accelerometer CFG_LAT_COLLISION_FROM_LEFT 1930
set accelerometer CFG_HARSH_FWD_ACCELERATION 300
set accelerometer CFG_HARD_BRAKING -250
set accelerometer CFG_CORNERING_RIGHT -590
set accelerometer CFG_CORNERING_LEFT 430

Get

Get the values of a single parameter or all accelerometer parameters

get accelerometer forward_collision get accelerometer all

Signal

The available signals for the accelerometer are:

Signal	Description
@accelerometer.forward_collision.signal	True when a forward collision is detected
@accelerometer.backward_collision.signal	True when a backward collision is detected
@accelerometer.lat_collision_from_right.signal	True when a collision from the right was detected
@accelerometer.lat_collision_from_left.signal	True when a collision from the left was detected
@accelerometer.harsh_fwd_acceleration.signal	True when a harsh acceleration was detected
@accelerometer.hard_braking.signal	True when a sudden braking was detected
@accelerometer.cornering_right.signal	True when hard cornering to the right was detected
@accelerometer.cornering_left.signal	True when hard cornering to the left was detected

Fieldset

You can append the actual g-force value and the exact time that the accelerometer signal was triggered with

$accelerometer.ACCELEROMETER_EVENT.value - appends the force in milli-g when the accelerometer event was triggered

$accelerometer.ACCELEROMETER_EVENT.time - appends the timestamp of when the accelerometer event was triggered (YYYY-MM-DDTHH:mm:ss.sssZ)

define fieldset default fields=$accelerometer.hard_braking.value,"time_of_hardbraking":$accelerometer.hard_braking.time

{
  ...
  "accelerometer.hard_braking.value": -340,
  "time_of_hardbraking": "2020-07-03T19:59:43.140Z"
}

ADAS

Actions and Signals List

ADAS is an accessory that allows you to obtain advanced information about the behavior of drivers on the road. It communicates via the ECU monitor.

Signals

The following table describes the list of signals available with the specific ADAS accessory you connect:

Comparison of Signals and Accessory

Description	Signal	Movon MDAS-9 Signal	Mobileye Signal
Brakes detecting	$ecu.brakes_enabled	✅	✅
FailSafe (Error state) detection	$ecu.failsafe	✅	✅
Forward collision warning detection	$ecu.forward_collision_warning	✅	✅
Headway measurement (in meters)	$ecu.distance_from_front_vehicle	✅	🚫
Headway measurement (in seconds)	$ecu.headway_measurement	✅	✅
Headway valid (boolean)	$ecu.headway_valid	✅	✅
Left and right signals	$ecu.left_signal & $ecu.right_signal	✅	✅
Left lane departure warning	$ecu.left_lane_departure_warning	✅	✅
Low and high beams detection	$ecu.low_beam_signal & $ecu.high_beam_signal	🚫	✅
Parked (zero speed) detection	$ecu.zero_speed	✅	✅
Pedestrian forward collision warning	$ecu.pedestrian_forward_collision_warning	✅	✅
Pedestrian in danger zone	$ecu.pedestrian_danger_zone	✅	✅
Relative speed from front of vehicle	$ecu.relative_speed_from_front_vehicle	✅	🚫
Right lane departure warning	$ecu.right_lane_departure_warning	✅	✅
Speed limit recognition	$ecu.speed_available	✅	✅
Time indicator	$ecu.time_indicator	🚫	✅
Wipers detection	$ecu.wipers_signal	🚫	✅

For a complete list of signals head to the Device Components Library. This section goes into details on specific signals.

$ecu.failsafe

True if the adas accessory triggers any of the following failsafe modes: blurred image, saturated image, low sun, partial blockage, or partial transparent.

$ecu.headway_warning_level	Description
0	When no CIPV (Close in path vehicle) is present
1	When a CIPV is present with Headway Warning > Headway Warning configured
2	When a CIPV is present with Headway Warning <= Headway Warning configured
3	When a CIPV is present with Headway Warning < 0.6

$ecu.time_indicator	Description
0	Day
1	Dusk
2	Night

$ecu.traffic_signs_recognition_warning_level	Description
0	Speed <= road speed
1	Speed > road speed + [0 - 5 km/h]
2	Speed > road speed + [5 - 10 km/h]
3	Speed > road speed + [10 - 15 km/h]
4	Speed > road speed + [15 - 20 km/h]
5	Speed > road speed + [20 - 25 km/h]
6	Speed > road speed + [25 - 30 km/h]
7	Speed > road speed + [30 - 35 km/h]
8	Speed > road speed + 35 km/h

$ecu.sound_type	Description
0	Silent
1	Lane departure warning Left
2	Lane departure warning Right
3	Headway warning 1
4	Traffic sign recognition
5	Urban forward collision warning
6	Forward collision warning + Pedestrian collision warning

# Forward collision warning detected 
define signal fcw $ecu.forward_collision_warning

# Night signal
define signal night_time $ecu.time_indicator == 2

# FCW at night event
define event fcw_at_night group=tracking fieldset=default ack=seq label=fcwnight trigger=fcw,night_time,and

Bluetooth

Actions and Signals List

Bluetooth allows you to pair and connect to a bluetooth speakerphone that support HFP bluetooth profiles (opens new window) only. Other bluetooth profile variations like JL-HFP, or HSP.HFP are not supported at the moment.

Scan and pair a bluetooth speakerphone with the apx-bt system tool. You can also use the Pegasus command console if you have access to it, simply write: >SSL followed by the bluetooth command

command	description
bluetooth scan seconds	Scans for this amount of seconds
bluetooth pair 'AABBCCDDEEFF'	Pair to a bluetooth device
bluetooth pair_forced 'AABBCCDDEEFF'	Force pairing
bluetooth unpair 'AABBCCDDEEFF'	Unpair from bluetooth device
bluetooth connect 'AABBCCDDEEFF'	Connect to bluetooth device
bluetooth disconnect 'AABBCCDDEEFF'	Disconnect from bluetooth device
bluetooth switch_audio 'AABBCCDDEEFF'	Switch main audio
bluetooth restart 'AABBCCDDEEFF'	Restart bluetooth
bluetooth reset 'AABBCCDDEEFF'	🛑 Resets bluetooth paired devices

>SSLbluetooth scan 15<
>SSLbluetooth connect 'AABBCCDDEEFF'<

command results	description
bluetooth info 'AABBCCDDEEFF'	Shows bluetooth info
bluetooth info_all 'AABBCCDDEEFF'	Shows all info
bluetooth list_discovered 'AABBCCDDEEFF'	Shows list of discovered
bluetooth list_paired 'AABBCCDDEEFF'	Shows list of paired
bluetooth list_connected 'AABBCCDDEEFF'	Shows list of connected

>SSLbluetooth list_discovered<
>RSL{"FC65DE2040E1":"Echo Show-1SN","7C6456A13E51":"[TV] Samsung Frame (43)","A0E6F8D3A66E":"Syrus 3GBT 05949"}<

Note that not all bluetooth devices that are discovered can be connected to for audio purposes, some bluetooth devices are connectable, but would not reproduce audio, check the bluetooth profile.

Actions

A possible action may be to connect to a separate speaker when you reach home

define action switch_bluetooth trigger=inside_home bluetooth connect '7C6456A13E51'

or force switch audio whenever the ignition turns on

define action force_audio trigger=ignition_on bluetooth switch_audio 'FC65DE2040E1'

Destinations

Bluetooth destinations can be defined to either broadcast messages to the S4GBT Destination Point characteristic or communicate with the user application console S4GBT User Application Console.

The main difference between the two is that the Destination Point characteristic only allows for messages to be notified, while the User application console allows you to write and read to that characteristic giving you the possibility of acknowledging messages.

Destination Point Characteristic

A sample configuration file (configuration.syrus.conf) may look like the following:

# create a group for bluetooth 
define group bluetooth

# fieldset for json message
define fieldset default fields=$gnss,$io

# create event definition
define event movement group=bluetooth ack=disabled fieldset=default trigger=@accelerometer.motion.signal

# set destination to bluetooth endpoint
set destinations group=bluetooth bt_event_destination

A sample destinations file (destinations.syrus.conf) may look like the following:

# bluetooth destination
define destination bt_event_destination json bluetooth://_:_ ack=disabled

In the above scenario the movement event will be generated and sent to the S4GBT Destination Point characteristic.

User Application Characteristic

This configuration allows you to enable acknowledgement for event messages allowing you to queue and de-queue once your application receives an event notification.

Note that only taip protocol can be used for message acknowledgement. A sample configuration file (configuration.syrus.conf) may look like the following:

# create a group for bluetooth 
define group bluetooth

# create fieldset for taip messages
define fieldset default fields=$gnss,$io

# create event definition
define event movement group=bluetooth ack=seq fieldset=default trigger=@accelerometer.motion.signal

# set destination to bluetooth endpoint
set destinations group=bluetooth bt_apps_destination

A sample destinations file (destinations.syrus.conf) may look like the following:

# bluetooth destination
define destination bt_apps_destination taip bluetooth://apps:_ ack=seq

In the above scenario the movement event will be generated and sent to the S4GBT User Application characteristic, the message will continue to be resent until it's ACK, see acknowledgement section for more info.

Counters

Actions and Signals List

Counters are vehicle metrics that can be instantiated and reported on a per event basis. The values of counters include total distance traveled, total ignition time, total time in idle, overspeeding, and others.

Create

To create a counter called: name you can define it as follow: define counters name

This automatically creates an internal count of the following fields.

Field	Description
odometer	Total distance traveled with ignition ON (meters)
ignition_time	Total ignition time (seconds)
idle_time	Total time spent in idling (seconds)
over_speed	Total time spent over speed (seconds)
over_rpm	Total time spent over RPMs (seconds)
hard_brakes	Total amount of hard brake events (count)
harsh_fwd_acceleration	Total amount of harsh forward acceleration events (count)

By default, these fields start at 0 but can be initialized from any value on the definition

define counters name [odometer] [ignition_time] [idle_time] [over_speed] [over_rpm] [hard_brakes] [harsh_fwd_acceleration]

• odometer field accepts mts, km, mile, ft
• time fields accepts sec, min, hr for seconds, minutes and hours.

So you could initialize the values of the counters like this:

define counters name odometer=23405km ignition_time=9502hr

The speed, rpm and idling times are controlled by the following threshold values:

Field	Default threshold	Description
speed_threshold	50kph	The over_speed counter will increase for every second the device is above this speed
rpm_threshold	3000rpm	The over_rpm counter will increase for every second the device is above this rpm
begin_idle_time	300sec	The idle_time counter begins to increase after (no movement detected AND ignition ON) for longer than the begin_idle_time

• speed_threshold field accepts mph, kph, m/s
• rpm_threshold fields accepts rpm, hz
• begin_idle_time fields accepts sec, min, hr

they can be set when you define the counter as follow:

define counters name [speed_threshold] [rpm_threshold] [begin_idle_time]

define counters name speed_threshold=80kph rpm_threshold=3500rpm begin_idle_time=180s

Set thresholds

You can change the threshold of the counter with set command:

set counters name field=value

set counters name odometer=12345mts
set counters name speed_threshold=80kph

Get

You can read the counters definition with

>>> get counters name
<<< define counters name speed_threshold=80mph begin_idle_time=350sec idle_time=3600sec ignition_time=3725sec

To get the value of the counters of a definition use the exec command:

exec apx-counter getall name

{"RPM_THRESHOLD":3000,"SPEED_THRESHOLD":55,"BEGIN_IDLE_TIME":5,"ODOMETER":0,"IGNITION_TIME":609,"IDLE_TIME":310,"OVER_SPEED":0,"OVER_RPM":0,"HARD_BRAKES":0,"HARSH_FWD_ACCELERATION":0}

💡Tip: to send the get or exec commands via TAIP use the >SSL prefix

Fieldset

The fieldsets can be defined with

field_name:$counters.name.field

For example if we have a counter defined called: driver1

define counters driver1 odometer=50925km

We can set the fields for that counter

define fieldset default fields=distance:$counters.driver1.odometer,ignition:$counters.driver1.ignition_time

Transmitting to Pegasus over TAIP If you are transmitting to Pegasus Gateway you'll need to define the following fieldset fields

Field	TAIP Equivalent
odometer	VO
ignition_time	CE
idle_time	CI
over_speed	CS
over_rpm	CR
hard_brakes	N/A, you can use a CV counter like CV00
harsh_fwd_acceleration	N/A, you can use a CV counter like CV01

define fieldset peg fields=VO:$counters.driver1.odometer,CE:$counters.driver1.ignition_time,CV00:$counters.driver1.hard_brakes

Actions

The following actions can be performed over counters:

Action	Description
start	Starts/resumes a counter
stop	Stops a counter
reset	Resets counter values back to 0.
resetall	Resets counter values back to 0 and changes the thresholds to the default values.
delete	Deletes a counter definition (make sure it's not being used in a fieldset)

The format is: action counters name

These actions can be added to an action definition, for example:

define signal john_connected $net_wifi.ssid==JOHN
define action trigger=john_connected start counters john
define action trigger=ignition_off,john_connected,not,or stop counters john

Signals

You can define signals with the counter values as follow:

define signal hourmeter500 $counters.john.ignition_time > 720000
define signal odometer20km $counters.john.odometer > 20000
define event hourmeter group=default fieldset=default ack=seq label=500hr code=25 trigger=hourmeter500
define event odometer group=default fieldset=default ack=seq label=20km code=25 trigger=odometer20km

Engine Control Unit (ECU)

Actions and Signals List

The ECU gives you the ability to read any engine parameter that a vehicle reports through its CAN bus interface. To configure and set up the ECU please visit the management tool section and read the corresponding ECU documentation.

Get Values

Once the ECU is reading data from the CAN bus you can retrieve values with:

get value $ecu.$id get value $ecu.$name

get value $ecu.fef4_1

get value $ecu.tires_provisioning

The $name and $id values come from the ECU directory (opens new window) from the SDK, if the parameter name is not listed then you'll always have the option to use the $id.

💡

Spreadsheet with the syruslang compatible Pegasus fields supported from the SDK for the ECU 🌎 Syrus 4 SDK ECU Keys + Pegasus Fields (opens new window)

Signals

Signals are constructed from the same convention as above using either the $name or $id from the ECU directory (opens new window)

define signal my_signal $ecu.$id define signal my_signal $ecu.$name

# signal definition using $id
define signal low_fuel $ecu.fefc_2 < 10

# signal definition using $name
define signal low_fuel $ecu.fuel_level < 10

💡 💡

parameters with Count units are reported in numerical decimal values, for example, seat belt switch

State	Syruslang equivalent	Meaning
00	0	NOT Buckled
01	1	OK - Seat Belt is buckled
10	2	Error - Switch state cannot be determined
11	3	Not Available

# true when the coolant temperature is > 100°C
define signal sg_coolant_temp $ecu.coolant_temp > 100

# true when the oil level is below 20%
define signal sg_oil_level $ecu.oil_level < 20

# true when the vehicle battery is < 8V
define signal sg_battery_power $ecu.battery_power < 8

# true when the the seat belt is buckled
define signal sg_seat_belt_buckled $ecu.seat_belt == 1

Diagnostic Trouble Codes

The diagnostic trouble codes for the ECU can be constructed using the field: $ecu.error_codes.

The fields to keep in mind are:

Field	Description
$ecu.error_codes.spn	Suspect Parameter Number
$ecu.error_codes.fmi	Failure Mode Identifier
$ecu.error_codes.cm	SPN Conversion Method
$ecu.error_codes.oc	Occurrence Count

An example of the fields reported can look like this:

{
	...
	"$ecu.error_codes.spn": 177,
	"$ecu.error_codes.fmi": 3,
	"$ecu.error_codes.cm": 0,
	"$ecu.error_codes.oc": 126
}

Thus you can use this to construct signals based on specific error codes detected.

# Engine Pre-filter Oil Pressure
define signal spn_oil_pressure $ecu.error_codes.spn == 1208

# FMI Voltage above normal
define signal fmi_voltage_above $ecu.error_codes.fmi == 3

# Event for Engine Oil Pressure Voltage Above Normal
define event engine_oil_pressure_voltage_above_normal group=tracking ack=seq label=diagoilpsi trigger=spn_oil_pressure,fmi_voltage_above,and

Fieldset

When working with TAIP protocol, you can set the fieldset $ecu and the ECU parameters read will automatically be transmitted as the corresponding TAIP values to an endpoint. You can also define your own fieldsets

define fieldset default fields="fuel_level":$ecu.fefc_2,"rpm":$ecu.rpm

{
  ...
  "fuel_level": 80,
  "rpm": 1430
}

Fatigue Sensor

Actions and Signals List

The fatigue sensor accessory can alert if a driver is falling asleep, depending on which fatigue sensor you install you could capture photos or videos that can be uploaded to an ftp server.

Signals

The following table describes the list of signals compatible with all fatigue sensor accessories that Syrus can interact with. Some signals are exclusive to a particular accessory, while some signals are fired by multiple accessories.

Note that the CAN BUS accessory signals are defined under /data/users/syrus4g/ecumonitor/definitions/ under a JSON file that describes the particular accessory, for example movon.

Fatigue Signals and Media Supported

Check the Fatigue Sensor's connect page for the accessories that support each type of media.

Description	Fatigue Sensor Signal	Photo	Video
Driver fatigue warning (yawning)	@fatigue_sensor.fatigue_warning	✅	✅
Driver fatigue reminder	@fatigue_sensor.fatigue_remind	✅	🚫
Driver fatigue alarm (drowsiness)	@fatigue_sensor.fatigue_alarm	✅	✅
Driver distracted	@fatigue_sensor.distraction	✅	✅
Driver not detected	@fatigue_sensor.no_portrait	✅	🚫
Driver on phone	@fatigue_sensor.phone	🚫	✅
Driver smoking	@fatigue_sensor.smoking	🚫	✅
Camera blocked	@fatigue_sensor.camera_blocked	🚫	✅
Photo captured	@fatigue_sensor.photo	✅	🚫

The following signals support photos:

Fieldsets

The fatigue sensor fields can be added with $fatigue_sensor for json protocol, if you're using taip there's no need to add fieldsets as it is done automatically whenever a photo is captured.

Sample payload

{
	"fatigue_sensor": {
		"state": "connected",
		"sensitivity": 3,
		"speaker_volume": 2,
		"min_speed": 10,
		"speeding": 50,
		"max_photos": 50,
		"nbr_photos": 24,
		"latest_photo": "1616442180-photo.jpeg"
	}
}

When using the CAN bus interface the sample payload will look like this

{
	"$ecu": {
		"yawning": 1,
		"drowsiness": 0,
		"distraction": 0,
		"driver_absence": 0,
		"phone": 0,
		"smoking": 0,
		"camera_blocked": 0,
		"fefc_2": 10
		...
	}
}

You can also build a payload to include fatigue sensor information

define fieldset fatigue fields=fatigue_alert:$ecu.fatigue_drowsiness

Events

To create events for the fatigue sensor and associate a photo you must specify which photo you want to associate with the photo param on an event definition.

photo=photo_source where photo_source can be

• fatigue_sensor - for the last photo captured by the fatigue sensor
• fatigue_sensor.fatigue_remind
• fatigue_sensor.fatigue_warning
• fatigue_sensor.fatigue_alarm
• fatigue_sensor.no_portrait
• fatigue_sensor.distraction
• fatigue_sensor.photo

Example events:

define event any_photo ack=seq group=tracking photo=fatigue_sensor label=ftgphoto trigger=@fatigue_sensor.signal
define event distracted ack=seq group=tracking photo=fatigue_sensor.distraction label=ftgdistrct trigger=@fatigue_sensor.distraction
define event nodriver ack=seq group=tracking photo=fatigue_sensor.no_portrait label=ftgnodrivr trigger=@fatigue_sensor.no_portrait

Actions

Fatigue sensor actions allow you to configure some fatigue sensor's parameters, or help you capture videos.

For the serial interface fatigue sensor accessory these are the list of compatible commands you can add to an action:

Command	Description
capture fatigue_sensor photo	Captures a photo with the fatigue sensor camera
upload fatigue_sensor photos	Manually upload all photos to an ftp destination
set fatigue_sensor sensitivity	Change sensitivity (Range: 2-11)
set fatigue_sensor speaker_volume	Change the speaker volume (Range: 0-2)
set fatigue_sensor minimum_speed	Change the minimum speed to trigger fatigue alerts (Range: 0-254)kph
set fatigue_sensor speeding_alarm	Change the speeding alarm (Range: 0-255)kph
set fatigue_sensor buffer_size	Change the max photos that can be captured (Range: 10-100)
set fatigue_sensor autoupload	Manage the auto upload of photos to the DCT ftp directory, default is 0
clear fatigue_sensor buffer	Deletes all photos in the fatigue_sensor directory

For the ethernet interface fatigue sensor accessory you can capture a video using an action with the create video command.

The create video command takes two parameters, the name of the video --name= (it's useful to have a timestamp as the start of the name of the video clip, **$gnss.timestamp**) and --time_win which is the time window back and forward in seconds to record a clip for.

Example:

# Ethernet Fatigue Sensor (Manufacturer: Movon, Model: MDSM-7)
define action ac_fatigue_alarm_drowsiness trigger=@fatigue_sensor.fatigue_alarm create video --name={{$gnss.timestamp}}-drowsiness --time_win=-10,+10
define action ac_fatigue_distraction trigger=@fatigue_sensor.distraction create video --name={{$gnss.timestamp}}-distraction --time_win=-10,+10
define action ac_fatigue_warning_yawning trigger=@fatigue_sensor.fatigue_warning create video --name={{$gnss.timestamp}}-yawning --time_win=-10,+10
define action ac_fatigue_phone trigger=@fatigue_sensor.phone create video --name={{$gnss.timestamp}}-phone --time_win=-10,+10
define action ac_fatigue_smoking trigger=@fatigue_sensor.smoking create video --name={{$gnss.timestamp}}-smoking --time_win=-10,+10
define action ac_fatigue_cam_blocked trigger=@fatigue_sensor.camera_blocked create video --name={{$gnss.timestamp}}-cam_blocked --time_win=-10,+10

Geofences

Actions and Signals List

Geofences definitions are managed by the apx-geofences tool, up to 3000 of them.

Syruslang will manage 1 namespace. Geofences can be defined in Syruslang the following format:

# circle
define geofence geofence_name [group=group_name] radius=50mts lon,lat

#polygon
define geofence geofence_name [group=group_name] lon1,lat1 lon2,lat2 lon3,lat3, ...

If no group is defined, the geofences will automatically belong to a group called: default.

The radius consists of a number, minimum 50 meters or 165 feet, followed by one of the following units mts, ft, km, mile for meters, feet, kilometers, and miles respectively.

Polygons consists of a minimum 3 coordinate pairs, up to 500 coordinate pairs.

geofence_name & group_name

The name and group of the geofence has to follow these guidelines:

• Case sensitive
• 3 to 50 characters
• 🛑 cannot start with a number!
• _ and - are the only allowed special characters
• [a-Z0-9][a-Z0-9_-]{3,50}

Once a geofence is defined the event engine evalutes the following signals constantly:

signal	Type	Description
$geofences.geofence_name.inside	boolean	True if geofence is inside
$geofences.geofence_name.time	number	Epoch timestamp of last geofence state change
$geofences.$groups.group_name.inside	boolean	True if geofence is inside any geofence in the group group_name
$geofences.$groups.group_name.outside	boolean	True if the geofence is outside all geofences in the group group_name

There is a also a fixed-signal @last_geofence which contains the last geofence that was modified, either by entering or exiting:

signal	Type	Description
@last_geofence.name	String	Name of the last geofence that was modified
@last_geofence.state	String	inside or outside state of the last geofence
@last_geofence.time	Number	Epoch timestamp of the last state change

geofences:

# two geofences in same group
define geofence hilton_blue_lagoon group=hotels radius=150mts -80.27856,25.78155
define geofence hilton_miami group=hotels radius=165ft -80.18867,25.79092

# one geofence in different group
define geofence dolphin_mall group=malls -80.38476,25.79042 -80.37606,25.79044 -80.37613,25.784339 -80.38449,25.78506

signals

# reference 1 geofence
define signal in_mall_for_30 min_duration=30min $geofences.dolphin_mall.inside

# reference any hotel
define signal in_any_hotel min_duration=20sec $geofences.$groups.hotels.inside

actions

# speak to a paired bluetooth speaker
define action parked_in_mall trigger=in_mall_for_30 speak 'welcome to {{@last_geofence.name}}'

# activate output 2
define action visit_hotel trigger=in_any_hotel set $io.out2 on

events

# entered hotel
define event arrived_at_hotel group=tracking fieldset=default ack=seq label=hotel code=40 trigger=in_any_hotel

# stay in mall
define event in_mall group=tracking fieldset=default ack=seq label=mall code=41 trigger=in_mall_for_30

IButton

Actions and Signals List

The ibutton is a onewire compatible accessory that is useful for driver identification. It is a key fob with a unique ID allowing you to 'add' or 'authorize' a particular ibutton on the device to take actions with. Note that a total of 500 onewire devices can be defined, this list is shared with the temperature sensor accessory.

The following examples will look at how to use the ibutton to identify drivers, for information on how to connect and configure the ibutton head to our accessories section.

To authorize an ibutton in syruslang use the following format:

add ibutton alias_name id

add ibutton driver1 91000014A0707F01

Once added, you can use the 'whitelisted' signal to take an action when that particular ibutton is presented since it's now authorized

# authorized driver
define signal auth_ibutton $ibutton.connected.whitelisted

# unauthorized driver
define signal unauth_ibutton $ibutton.connected.whitelisted == false

# action to deactivate output1 if driver authorized
define action auth_driver_deactivate_out trigger=auth_ibutton set out1 off

# action to activate output2 if driver is unauthorized
define action unauth_activate_out trigger=unauth_ibutton set out2 on

Fieldset

In order to append ibutton data to your event fields you can use the $ibutton field for JSON protocol.

define fieldset json_ibutton fields=$ibutton

{
	"$ibuttons": [
		{
			"alias": "driver1",
			"id": "123456789012345",
			"whitelisted": true,
			"connected": true,
			"conn_epoch": 1608048266,
			"disc_epoch": 1608048273
		}
	]
}

for TAIP protocol you have two possibilities, either the last value read, or the current value.

define fieldset taip_current_ibutton fields=IB:$ibutton.connected.id
define fieldset taip_last_ibutton fields=IS:$ibutton.last.id

MDT

Actions and Signals List

MDT or Mobile Data Terminal is a mode that the Syrus can be configured in which allows you to receive data via the device's rs-232 serial port, encapsulate it and send it to a destination.

To get started make sure you follow the installation instructions in our connect page.

Once you have the serial accessory connected and it's transmitting data periodically via the serial port you can configure an event upon an incoming mdt message with the following signal @mdt.message.

Note, it's recommended that you do not mix this with other signals ​

define event incoming_message group=mdt fieldset=default code=0 trigger=@mdt.message

When a message is received the event will generate and the data appended to a json message will come in $mdt message

{
	"$mdt": {
		"message": "68656c6c6f20776f726c64"
	}
}

For TAIP protocol you don't need to add the field, as long as you define the event with @mdt.message it will generate and send to the server.

Actions

You can set the MDT settings with the set mdt command, and send a message with send mdt message

set mdt '115200 x 1 5 0 0 0 0'

define action ignition_on_send_msg trigger=signal_ign_on send mdt message '0304020d0a'

Power Save Mode

Actions and Signals List

Power save mode is a low power consumption state that the device can enter automatically after it meets specific criterias based on time and GPIO status. This is important for Syrus devices installed in vehicles that need to conserve energy after the vehicle's ignition switch is OFF. By default the device enters power save mode after 5 minutes of no ignition being detected.

The actual programming of the power save mode can be done locally on the device or remotely in the Syrus Cloud profile page. This section describes the available signals and actions that you can take for the power saving mode.

Get

To get the current power save mode value use:

get power_save mode

The device will respond with the PSM_string, example: "IGN:0;IGN;300"

Signal

You can use the following signals to trigger events for when the device goes to sleep and wakes up: @power_save.sleep, @power_save.wakeup

define event sleeping group=default ack=seq label=slp trigger=@power_save.sleep
define event awake group=default ack=seq label=wake trigger=@power_save.wakeup

as well as individual signals like @power_save.time or @power_save.motion

define event wake_by_time group=default ack=seq label=wake trigger=@power_save.time
define event wake_by_motion group=default ack=seq label=wake trigger=@power_save.motion

Action

You can also start the power saving mode as part of an action, in order to trigger the power save mode when you want.

define action gotosleep trigger=inside_geofence,parked,and set power_save immediate

Note that when you do an immediate power save the device will wake up according to the wakeup_condition and use the wait_time again to go back to sleep.

Fieldset

You can configure the following fieldsets to send you relevant information on a payload

$power_save.mode - appends the current power save mode string $power_save.status - true when the power save mode is ON $power_save.reason - appends the reason for waking up

{
  ...
  "power_save.mode": "IGN:0;IGN;300",
  "power_save.status": true,
  "power_save.reason": "ign"
}

Satcom/Sigfox

Actions and Signals List

The Satcom/sigfox feature is available through accessories that communicate via the serial rs232 interface. With these accesories you're able to send events and communicate with Iridium's™ or Sigfox's networks.

The following examples will look at how to use get started using the satcom or sigfox with syruslang, for information on how to connect and configure the satcom/sigfox head to our accessories section.

The typical usecase here is to use the respective networks as data destinations whenever there's no connectivity available, typically as a backup connectivity solution. So by default when you create the destination you'll want to set them 'disabled', and 'enable' them when a condition like 'no_connectivity' occurs.

To create the destination use:

save on the destinations.syrus.conf file

define destination satcom_destination taip satcom://_:_ ack=disabled disabled=true

Once defined you can control when to enable these destinations with an action

save on the configuration.syrus.conf file

define action enable_satcom trigger=disconnected enable destination satcom_destination

define action disable_satcom trigger=disconnected,not disable destination satcom_destination

Next, you'll want to configure what disconnected means, so that signal can look like the following:

# defines disconnected as more than 600 seconds with no connection from the modem
define signal disconnected $modem.no_conn_time > 600

Finally you're able to create events that get sent to the satcom_destination when the device detects that it's disconnected

# create a group for the events
define group satmsgs

# create a fieldset to append satcom information to the event messages 
define fieldset satcom_fields fields=$satcom

# event when no connection
define event start_satcom group=satmsgs fieldset=satcom_fields ack=disabled label=stcm code=10 trigger=disconnected

# set destination for satmsgs to satcom destination
set destinations group=satmsgs satcom_destination

Fieldset

The Fieldset compatible with the satcom is $satcom, for both TAIP & JSON protocols.

TAIP protocol appends the Satcom ID to the message.

>REVXX...;II=300234063907660<

JSON protocol appends the satcom payload.

{
	"state": "connected",
	"type": "satcom",
	"id": "300234063907660",
	"signal": 5,
	"version": 15,
	"buff_size": 50,
	"buff_count": 1
}

Commands

The available commands to interact with the satcom are:

set buffer size:

set satcom buffer_size [10-500]

example: set satcom buffer_size 50

Note that the buffer is circular, where the oldest message is deleted after it reaches the buffer_size

get satcom buffer_size

To clear the buffer you can send

clear satcom buffer

Speak

Actions and Signals List

The speak command converts text to speech over a paired bluetooth audio handset.

Action

define action my_action trigger=my_signal speak "Text to speak"

You can pass an argument called lang to specify the language. Supported languages are found in the apx-tts tool, use the first two letters of the language you want to use on the argument.

Example to have the action trigger speak in French language.

define action speak_in_french trigger=my_signal speak lang=fr "Texte pour parler"

Speak with no arguments uses the English language.

Temperature Sensor

Actions and Signals List

Temperature can be read via the onewire (1-wire) cable and compatible temperature sensor probes. Note that a total of 500 onewire devices/sensors can be defined, so this list is shared with ibutton sensors for example.

To add a temperature sensor via syruslang use the following format:

add temperature_sensor alias_name id

add temperature_sensor mytemp 8D01144D07DBAA28

You can then use the temperature value of mytemp to create signals and actions

# temperature goes above 0°C
define signal temp_above_threshold min_duration=10sec $temp.aliases.mytemp.value > 0

# action to activate output 2 if threshold reached
define action above_temp_output_on trigger=temp_above_threshold set out2 on

Fieldsets

The fieldset definition for the temperature sensor can be done in JSON format by adding $temp as a field.

define fieldset temperature fields=$temp

{
	"$temp": [
		{
			"alias": "tempsen1",
			"id": "8D01144D07DBAA28",
			"value": 22.625,
			"connected": true,
			"epoch": 1608047806
		},
		{
			"alias": null,
			"id": "3C12345D07DBAB29",
			"value": 22.437,
			"connected": true,
			"epoch": 1608047807
		}
	]
}

The TAIP format for Pegasus Gateway (opens new window) is also supported, up to 3 temperature sensor probes can send data in the following fields: EA_A, EA_B, and EA_C.

To reference the data you can use a temperature sensor alias, or the nth position.

define fieldset taip fields=EA_A:$temp.aliases.temp1.value,EA_B:$temp.aliases.temp2.value,EA_C:$temp.aliases.temp3.value

Timers

Actions and Signals List

Timers can be defined to create conditions based on time for your configuration. For example, you may use timers to count how long an input is activated, or perform an action after certain time has passed.

To define a timer:

define timer timer_name duration [delay] [repeat] [enabled]

parameters	type	description
timer_name	string	name of the timer, can be referenced with @timers.timer_name as a signal
duration	string	duration in #A format, where # is a digit and A represents the unit of time, as soon as this duration expires it will transition the signal to true, valid units are sec, min, hr
delay	string	optional duration in #A format, this is the amount of time the timer will wait to start counting the duration
repeat	boolean	optional true if you want the timer to repeat and its signal to transition to 'true' every time it reaches the duration value (false by default)
enabled	boolean	optional true if the timer is enabled (true by default)

example timer called timer_name that waits 5 seconds to start a 10second timer and repeats every 10 seconds.

define timer timer_name duration=10sec [delay=5sec] [repeat=true] [enabled=true]

Given the parameters above, we can define timers to be:

1. One-shot: these timers fire once they reach the defined value
2. Recycled: these timers fire every time they reach the defined value

One-shot

define timer my_one_shot_timer duration=#A

# create a 5 minute counter
define timer one_shot duration=5min

# event one_time will fire after the timer reaches its value
define event one_time group=default fieldset=default ack=seq trigger=@timers.one_shot

Recycled

define timer my_recycle_timer duration=#A repeat=true

# create a 1 minute counter
define timer recycled duration=2min repeat=true

# event every_time will fire every time the timer reaches its value
define event every_time group=default fieldset=default ack=seq trigger=@timers.recycled

Controlling timers

Timers can be controlled via the following commands

start timer timer_name

stop timer timer_name

These commands can be defined as part of an action, to trigger an event after X minutes of input1 ON for example

define timer timer_name duration=1min

define action start_timer trigger=input1_on start timer timer_name
define action stop_timer trigger=input1_off stop timer timer_name

Here's a more elaborate example that you can use to trigger an output activation after the ignition is ON, until a valid ibutton is presented

# create timer for unauthorized 
define timer unauthorized duration=15min delay=15sec repeat=true enabled=true

# create signals for ignition, output2 and authorized ibutton
define signal sg_ignition_on $io.ign
define signal sg_output2_on $io.out2
define signal authorized $ibutton.connected.whitelisted

# activate output2 when timer expires and the output is not active
define action output_activate trigger=@timers.unauthorized,authorized,not,sg_output2_on,not,and,and set output2 on

# stop timer and deactivate output2 when an authorized iButton is detected
define action stop_timer trigger=authorized stop timer unauthorized
define action deactivate_output trigger=authorized set output2 off

TPMS Sensor

Actions and Signals List

The TPMS feature is available via an accessory that's connected to the vehicle's onboard computer via the Syrus4's ECU module.

To get started make sure your j1939_params file has the PGN FEF4 defined, with the following START_POSITION's: 2, 3-4, 1, 5.1, 5.3, 5.7, 8.1, 8.6.

The list of compatible parameters can be found in the SDK under the ecu directory ECU.d/fef4.json (opens new window).

PGN+SPN	param_name
fef4_1	tires_provisioning
fef4_2	tires_pressure
fef4_3-4	tires_temperature
fef4_5.1	tires_sensor_enable_status
fef4_5.3	tires_air_leak_status
fef4_5.7	tires_temperature_state
fef4_8.1	tires_trailer_flag
fef4_8.6	tires_pressure_state

Signals

Signals for the TPMS integration can be defined on a per tire basis, the format is defined as follow:

$ecu.$tires.axle_X.tire_Y.value

Where X is the axle, Y is the tire position, and value is the corresponding value for the previous fields mentioned.

# signals for low pressure and high temperature for front tires
define signal tire_lf_pres $ecu.$tires.axle_1.tire_1.pressure < 80
define signal tire_lf_temp $ecu.$tires.axle_1.tire_2.temperature > 100
define signal tire_rf_pres $ecu.$tires.axle_1.tire_1.pressure < 80
define signal tire_rf_temp $ecu.$tires.axle_1.tire_2.temperature > 100

You can also define signals for particular SPNs related to the tire's condition, for example the sensor_enable_status which uses the following values:

Signal/Sensor Status	Description
0	Signal missing
1	Signal OK
2	Not defined
4	Not valid, waiting after power-up

define signal signal_lf_missing $ecu.$tires.axle_1.tire_1.sensor_enable_status == 0
define signal signal_rf_missing $ecu.$tires.axle_1.tire_2.sensor_enable_status == 0

Fixed Signals A list of fixed signals are predefined that fire whenever a tpms accessory detects a critical condition such as under inflation or air leak in one of the tires. These signals can be used to fire an immediate action or generate an event:

# action to send an audible alert to a BT speakerphone alerting an air leak detected (rated at 1 fire every 2 hours)
define action air_leak_detected rate=1/2hr trigger=@tpms.tire_leak speak 'Air leak detected on a tire, please pull over'

Refer to the list of possible fixed signals on the ECU components library section

Fieldsets

If you're using taip protocol format you'll just need to add $ecu as a field to include all the relevant TPMS data.

For json protocol there's 2 general fieldsets to be defined, $ecu which contains the raw data values and $tpms which contains the alerts information. The raw data values format is the following:

"Axle, Tire, Value ; Axle, Tire, Value ; etc.."

Examples:

"tires_provisioning": "2,1,33.00;5,4,84.00;2,3,35.00;1,1,17.00;0,2,2.00;0,1,1.00;1,2,18.00",
"tires_pressure": "2,1,80.00;5,4,276.00;2,3,80.00;1,2,148.00",
"tires_temperature": "2,1,1639.91;5,4,369.41;2,3,-136.38;1,2,21.00",
"tires_sensor_enable_status": "2,1,0.00;5,4,0.00;2,3,0.00",
"tires_air_leak_status": "2,1,3.00;5,4,3.00;2,3,3.00;1,1,3.00;0,2,3.00;0,1,3.00;1,2,3.00",
"tires_temperature_state": "2,1,0.00;5,4,0.00;2,3,0.00;1,1,0.00;0,2,0.00;0,1,0.00;1,2,0.00",
"tires_trailer_flag": "2,1,1.00;5,4,1.00;2,3,1.00;1,1,1.00;0,2,1.00;0,1,1.00;1,2,1.0",
"tires_pressure_state": "2,1,0.00;5,4,0.00;2,3,0.00;1,1,0.00;0,2,0.00;0,1,0.00;1,2,0.00",

💡 Note: The units for pressure and temperature values in the json format are kPa and °C

The data is further broken down into a $tpms object, which introduces structure of an array of objects for each alert reported, that corresponds to the tires that meet that particular alert. For example, if multiple tires report critical under pressure you'll receive a json with the following fields

{
	"tpms": {
		...
		"under_inflation_warning": [],
		"under_inflation_critical": [
			{
				"pressure": 103,
				"temperature": 100.91,
				"provisioning": 33,
				"sensor_enable_status": 0,
				"air_leak_status": 3,
				"temperature_state": 0,
				"pressure_state": 0,
				"trailer_flag": 1,
				"axle_index": "0",
				"axle": "1",
				"tire": "1"
			},
			{
				"pressure": 99,
				"temperature": 100.38,
				"provisioning": 35,
				"sensor_enable_status": 0,
				"air_leak_status": 3,
				"temperature_state": 0,
				"pressure_state": 0,
				"trailer_flag": 1,
				"axle_index": "0",
				"axle": "1",
				"tire": "3"
			},
			...
		]
	}
}

define fieldset pegasus fields=$io,$gnss,$net,$ecu

define fieldset raw_ecu fields=ecu:$ecu

define fieldset tpms_alerts fields=tpms:$tpms

define fieldset tpms_under_pressure fields=under_inflated_tires:$tpms.under_inflation_critical

Tracking Resolution

Actions and Signals List

The tracking resolution is a special reporting criteria that can be configured on the device to provide periodic updates based on time, heading change, or distance. The conditions use a logical OR operator between them and once ANY condition is met the count of the other criterias is reset.

Start by defining a tracking_resolution

define tracking_resolution custom_name [heading] [time] [distance]

The heading, time, and distance fields are optional as long as there's at least 1 defined. To define use a number # followed by the corresponding unit

Possible units:

unit	type	Description
deg	heading	degrees from North (0), increasing eastwardly, NorthEast (45), East (90), etc.
rad	heading	radians
sec	time	seconds
min	time	minutes
hr	time	hours
mile	distance	miles
ft	distance	feet
mts	distance	meters
km	distance	kilometers

for example 30sec, refers to time of 30 seconds, 3km, refers to 3 kilometers.

examples

# standard tracking resolution of 30 degrees, or 60 seconds, or 500 meters
define tracking_resolution standard 30deg 60sec 500mts

# distance only tracking resolution, every 1km
define tracking_resolution dist_only 1km

Once you define a tracking_resolution, the following signals transition to true depending on the criteria used for the periodic reporting:

signal	meaning
@tracking_resolution.custom_name.signal	True when any metric for tracking_resolution custom_name reaches its periodicity
@tracking_resolution.custom_name.heading	True for tracking_resolution custom_name when heading delta is met
@tracking_resolution.custom_name.distance	True for tracking_resolution custom_name when distance is met
@tracking_resolution.custom_name.time	True for tracking_resolution custom_name when time is met

just be sure to replace custom_name with the name you used for the tracking_resolution

signal	meaning
@tracking_resolution.moving.signal	True every 30deg or 60sec or 500 mts
@tracking_resolution.moving.time	True 60 seconds

All we need to do now is add some actions to set the tracking_resolution to one of the values we defined earlier. We'll start by creating two signals for when the Ignition is ON and OFF.

define signal ignitionON min_duration=5sec $io.ign == true         
define signal ignitionOFF min_duration=5sec $io.ign == false       

Now we'll use this on our actions

define action start trigger=ignitionON set tracking_resolution standard 30deg 60sec 500mts
define action end trigger=ignitionOFF set tracking_resolution standard 2hr

Now we have the tracking resolution update every time the ignition is ON and OFF.

Finally we'll create an event to go along with this:

define event track group=tracking ack=seq label=trckpnt code=0 trigger=@tracking_resolution.standard.signal

Variables

Actions and Signals List

Variables can be defined to be later used throughout the configuration.

For example:

define variable my_variable "hello world"

The value of this variable can be accessed with: $variables.my_variable

The value can also be updated with the following instruction:

set variable my_variable "good bye"

Thus it can be used in actions:

define variable person "john smith"

# change the variable person to 'jess johnson'
define action change_person trigger=my_signal set variable person "jess johnson"

# used in a fieldset
define fieldset info fields="driver_name":$variables.person

# as a signal and part of an event
define signal jess $variables.person == 'jess johnson'
define event my_event group=tracking fieldset=info ack=seq label=name trigger=jess,speeding,and 

# used in a speak command ('current driver jess johnson')
define action driver_speak trigger=my_signal speak 'current driver {{$variables.person}}'

Video

Actions and Signals List

Capture videos based on events and stream in real time.

Commands

The following commands can be placed at any point in your configuration or as part of an action.

Command	Description	Parameters
start recording	starts a video recording	--camera, --resolution
stop recording	stop recording	--camera, --resolution
create video	creates a video recording	--name, --camera, --time_win

Parameters	Description	Example
--camera	name of the camera	--camera=driver_cam
--resolution	video resolution, SD, HD, or FHD	--resolution=HD
--time_win	time window for video capture, format: -SEC,+SEC	--time_win=-20,+10
--name	name of the video clip*	--name=my_event_name

Tip: it's useful to give the name a unique value like a timestamp $gnss.timestamp

Actions

The commands previously defined can be used as actions to capture video clips based on specific events, or start video history recording

# start video recording on camera 'frontcam' after the engine is ON
define action ignon_start_video trigger=ignitionOn start recording --camera=frontcam

# end video recording on all cameras after the engine is turned OFF
define action ignoff_end_video trigger=ignitionOff stop recording

# capture video 30 seconds before and 10 seconds after cornering left is detected
define action cornering_with_vid trigger=@accelerometer.cornering_left.signal create video --name={{$gnss.timestamp}}_cornering_left --time_win=-30,+10

# capture video 10 seconds before and 5 seconds after hard braking is detected 
define action hard_braking_with_vid trigger=@accelerometer.hard_braking.signal create video --name={{$gnss.timestamp}}_hard_braking --time_win=-10,+5

Tip: You can use Syruslang commands to enable/disable wifi, ethernet, or hotspot which is required for video cameras

Configuration walkthrough

Pegasus Example

For this example we'll be building a basic tracking script that will perform the following:

• Report to Pegasus Destination with TAIP over TCP
• Report the device's inputs/outputs, gnss, network, and counters data
• Event while the ignition is ON with the label: trckpnt
  • Every 45deg, 1min, or 500 meters
• Event while the ignition is OFF with the label: prdtst
  • Every 2hr
• Event with the label ignon once the ignition is turned ON
• Event with the label ignoff once the ignition is turned OFF
• Event with the label panic once the input 1 is pressed

0. Create a configuration file

• Create a new file on a text editor and save it with name.syrus.conf (for this example we'll use configuration.syrus.conf)
• The configuration will have all the signals, actions, events, etc. definitions

1. Create the signals for the events

• Once you have the file the first step is to always define the signals we're going to use throughout the script.

define signal signal_ign_on $io.ign == true
define signal signal_ign_off $io.ign == false
define signal signal_in1_on $io.in1 == true

Now we can use signal_ign_on, signal_ign_off, signal_in1_on throughout the configuration to trigger any actions and events.

2. Define tracking resolution

• The next step is to create the tracking resolutions we're going to use for this configuration.
• Since we're going to report two different events based on the ignition state we'll need to define 2 separate tracking_resolutions

define tracking_resolution track_res_ignon 45deg 60sec 500mts
define tracking_resolution track_res_ignoff 0deg 120min 0mts

💡 Tip: Notice how the names of the definitions have a reference to the actual definition it's defining in front

3. Create the actions for the tracking resolution

• The tracking resolutions need to be controlled by an action so that we suspend and resume them when the ignition state changes.
• In this case we need the track_res_ignon to start whenever the ignition is turned ON, and stop whever it turns OFF, and vice versa: we need the track_res_ignoff to start whenever the ignition is turned OFF, and stop whenever the ignition is turned ON.
• Actions are controlled by a trigger, which is a combination of the signals we created earlier
• In this case the corresponding actions are:

define action action_start_ignon trigger=signal_ign_on set tracking_resolution track_res_ignon 45deg 60sec 500mts
define action action_stop_ignon trigger=signal_ign_off set tracking_resolution track_res_ignon 0deg 0sec 0mts

define action action_start_ignoff trigger=signal_ign_off set tracking_resolution track_res_ignoff 0deg 120min 0mts
define action action_stop_ignoff trigger=signal_ign_on set tracking_resolution track_res_ignoff 0deg 0sec 0mts

4. Create the groups for events and fieldsets

• Before we can define a fieldset and an event, we need to create a group to associate them to.

define group group_default

5. Create the counters for odometer, engine on, idling, etc.

• The counters are required for correct functionality on Pegasus
• You can override the default values for speed threshold, when to begin the idling time, etc.

define counters globals speed_threshold=90kph rpm_threshold=3000rpm begin_idle_time=300sec odometer=123456mts ignition_time=11043sec

6. Create the fieldset

• Since we're going to report via TAIP on Pegasus, you're going to want to use the $io, $gnss, $net, and some specific $counters fields exclusive for Pegasus so it can work properly.

define fieldset fieldset_default fields=$io,$gnss,$net,VO:$counters.globals.odometer,CE:$counters.globals.ignition_time,CL:$counters.globals.idle_time,CS:$counters.globals.over_speed,CR:$counters.globals.over_rpm

7. Create the events

• We create the events and add a label so that Pegasus can identify them. This step ties the fieldset, group, and signals together. Remember to use the signals we defined in step 1 to create the triggers.

define event event_ignon group=group_default fieldset=fieldset_default ack=seq label=ignon trigger=signal_ign_on
define event event_ignoff group=group_default fieldset=fieldset_default ack=seq label=ignoff trigger=signal_ign_off
define event event_panic group=group_default fieldset=fieldset_default ack=seq label=panic trigger=signal_in1_on
define event event_tracking group=group_default fieldset=fieldset_default ack=seq label=trckpnt trigger=@tracking_resolution.track_res_ignon.signal
define event event_parked group=group_default fieldset=fieldset_default ack=seq label=prdtst trigger=@tracking_resolution.track_res_ignoff.time

8. Create the destination

• Until now, steps 0-7 have all been on the main configuration file, this step requires you to create a new file: destinations.syrus.conf and add the destination definition to that file.

define destination destination_peg1 taip tcp://pegasus1.peginstances.com:5001

• The convention for the url is pegasus followed by the pegasus_id, and the port is 5000 + the pegasus_id, you can view your pegasus_id in the /api (opens new window) endpoint of your Pegasus Gateway

9. Tie the events generated with the endpoint

• Go back to the main configuration file and set the destination for the group of events we defined earlier.

set destinations group=group_default destination_peg1

• Save that file as configuration.syrus.conf, and the other file (with the single define destination line) as destinations.syrus.conf and it's ready to be uploaded to SyrusJS.

configuration.syrus.conf with comments:

# signal definitions
define signal signal_ign_on $io.ign == true
define signal signal_ign_off $io.ign == false
define signal signal_in1_on $io.in1 == true

# tracking resolutions
define tracking_resolution track_res_ignon 45deg 60sec 500mts
define tracking_resolution track_res_ignoff 0deg 120min 0mts

# actions
define action action_start_ignon trigger=signal_ign_on set tracking_resolution track_res_ignon 45deg 60sec 500mts
define action action_stop_ignon trigger=signal_ign_off set tracking_resolution track_res_ignon 0deg 0sec 0mts

define action action_start_ignoff trigger=signal_ign_off set tracking_resolution track_res_ignoff 0deg 120min 0mts
define action action_stop_ignoff trigger=signal_ign_on set tracking_resolution track_res_ignoff 0deg 0sec 0mts

# group
define group group_default

# counters
define counters globals speed_threshold=90kph rpm_threshold=3000rpm begin_idle_time=300sec odometer=0mts ignition_time=0sec

# fieldset
define fieldset fieldset_default fields=$io,$gnss,$net,VO:$counters.globals.odometer,CE:$counters.globals.ignition_time,CL:$counters.globals.idle_time,CS:$counters.globals.over_speed,CR:$counters.globals.over_rpm

# events
define event event_ignon group=group_default fieldset=fieldset_default ack=seq label=ignon trigger=signal_ign_on
define event event_ignoff group=group_default fieldset=fieldset_default ack=seq label=ignoff trigger=signal_ign_off
define event event_panic group=group_default fieldset=fieldset_default ack=seq label=panic trigger=signal_in1_on
define event event_tracking group=group_default fieldset=fieldset_default ack=seq label=trckpnt trigger=@tracking_resolution.track_res_ignon.signal
define event event_parked group=group_default fieldset=fieldset_default ack=seq label=prdtst trigger=@tracking_resolution.track_res_ignoff.time

# set destination
set destinations group=group_default destination_peg1

destinations.syrus.conf with comments:

# pegasus endpoint 
define destination destination_peg1 taip tcp://pegasus1.pegasusgateway.com:5001

MQTT Example

For this example we'll send temperature data to an MQTT endpoint:

• Create a temperature sensor (Probe A)
• When temperature of Probe A > 0°C report alert and activate output 2
• When temperature of Probe A <= 0°C report alert and deactivate output 2
• Report temperature data periodically to test.mosquitto.org over mqtt

0. Create a configuration file

• Create a new file on a text editor and save it with name.syrus.conf (for this example we'll use configuration.syrus.conf)
• The configuration will have all the signals, actions, events, etc. definitions

1. Connect and add the temperature sensor

• Follow the steps on the connect section to read the temperature sensor unique ID
• Add the temperature sensor probe on syruslang

add temperature_sensor probe_a XXXXXXXXXXXXXXXX

2. Create the signals for the actions when the probe reaches a temperature

• It's recommended to use a min_duration to confirm the reading is stable at a certain value
• To reach the temperature sensor we just defined we use $temp.aliases. followed by the name given to the sensor and .value to get the temperature value

define signal sg_temp_above_threshold min_duration=10sec $temp.aliases.probe_a.value > 0
define signal sg_temp_below_threshold min_duration=10sec $temp.aliases.probe_a.value <= 0

• We'll need a signal to control the tracking_resolution, which is the periodic report of the temperature sensor
• In this case we can use the power state of the device (remember that the operator and value == true is optional when creating the signal)

define signal sg_power_on min_duration=2sec $io.pwr

3. Define the tracking resolution

• The next step is to create the periodic report, for this we create a tracking_resolution
• For this example we'll only use one tracking_resolution at a fixed interval every 20sec

define tracking_resolution tr_periodic 20sec

4. Create the actions for the tracking resolution and temperature output manipulation

• We can use the power state to control the action of the tracking resolution
• In this case if power is detected we can start the tracking resolution, and pause it if power is disconnected

define action ac_start_pwron trigger=sg_power_on set tracking_resolution tr_periodic 20sec
define action ac_stop_pwroff trigger=sg_power_on,not set tracking_resolution tr_periodic 0sec

• For the action of the output 2 control we can use the signals we defined earlier: sg_temp_above_threshold & sg_temp_below_threshold

define action ac_out_on_above_temp trigger=sg_temp_above_threshold set output2 on
define action ac_out_off_below_temp trigger=sg_temp_below_threshold set output2 off

5. Create the groups for events and fieldsets

• Before we can define a fieldset and an event, we need to create a group to associate them to.

define group gr_default

6. Create the fieldset

• We're going to want to add temperature, location, and time information to our mqtt payload, to do this we define a field set with those device components

define fieldset fs_default fields=$temp.aliases.probe_a,$gnss.latitude,$gnss.longitude,$timestamp

7. Create the events

• We create the events that trigger when the signals are met
• It's a good idea that we add the power_on signal as an "AND" condition to the temperature threshold
• All events will be tagged with the fields mentioned in the fieldset fs_default created earlier

define event ev_pwron group=gr_default fieldset=fs_default ack=seq trigger=sg_power_on
define event ev_pwroff group=gr_default fieldset=fs_default ack=seq trigger=sg_power_on,not
define event ev_temp_above group=gr_default fieldset=fs_default ack=seq trigger=sg_temp_above_threshold,sg_power_on,and
define event ev_temp_below group=gr_default fieldset=fs_default ack=seq trigger=sg_temp_below_threshold,sg_power_on,and
define event ev_periodic group=gr_default fieldset=fs_default ack=seq trigger=@tracking_resolution.tr_periodic.time

8. Create the destination

• Until now, steps 0-7 have all been on the main configuration file, this step requires you to create a new file: destinations.syrus.conf and add the destination definition to that file.

define destination mosquitto json mqtt://test.mosquitto.org:1883 protocol="mqtt" publish="{{$modem.imei}}/pub"

9. Tie the events generated with the endpoint

• Go back to the main configuration file and set the destination for the group of events we defined earlier.

set destinations group=gr_default mosquitto

• Save that file as configuration.syrus.conf, and the other file (with the single define destination line) as destinations.syrus.conf and it's ready to be uploaded to SyrusJS.

configuration.syrus.conf with comments:

# add temperature sensor probe_a (replace XXXXXXXXXXXXXXXX with sensor id)
add temperature_sensor probe_a XXXXXXXXXXXXXXXX

# create signals for when the temperature is above or less than 0
define signal sg_temp_above_threshold min_duration=10sec $temp.aliases.probe_a.value > 0
define signal sg_temp_below_threshold min_duration=10sec $temp.aliases.probe_a.value <= 0

# create a signal for when the power is ON
define signal sg_power_on min_duration=2sec $io.pwr

# create the periodic resolution every 20 seconds
define tracking_resolution tr_periodic 20sec

# actions to control the periodic report based on the power state
define action ac_start_pwron trigger=sg_power_on set tracking_resolution tr_periodic 20sec
define action ac_stop_pwroff trigger=sg_power_on,not set tracking_resolution tr_periodic 0sec

# actions to control the output 2 based on the temperature reading
define action ac_out_on_above_temp trigger=sg_temp_above_threshold set output2 on
define action ac_out_off_below_temp trigger=sg_temp_below_threshold set output2 off

# create a group to associate multiple events
define group gr_default

# create a list of fields to append to the events generated
define fieldset fs_default fields=$temp.aliases.probe_a,$gnss.latitude,$gnss.longitude,$timestamp

# create the events or alerts that trigger whenever the signals previously defined are met
define event ev_pwron group=gr_default fieldset=fs_default ack=seq trigger=sg_power_on
define event ev_pwroff group=gr_default fieldset=fs_default ack=seq trigger=sg_power_on,not
define event ev_temp_above group=gr_default fieldset=fs_default ack=seq trigger=sg_temp_above_threshold,sg_power_on,and
define event ev_temp_below group=gr_default fieldset=fs_default ack=seq trigger=sg_temp_below_threshold,sg_power_on,and
define event ev_periodic group=gr_default fieldset=fs_default ack=seq trigger=@tracking_resolution.tr_periodic.time

# set the destination of the group of events gr_default to mosquitto
set destinations group=gr_default mosquitto

destinations.syrus.conf with comments:

# mqtt endpoint mosquitto where the events from group gr_default will report to
define destination mosquitto json mqtt://test.mosquitto.org:1883 protocol="mqtt" publish="{{$modem.imei}}/pub"

Message broker interaction

SyrusJS uses the redis application message broker to store its signal states and queues.

The possible keys stored are

Message acknowledgments with destinations (type: string) /data/app_data/<instance_name>_<destination>_ack

Messages in queue waiting to be sent to destination (type: list) /data/app_data/<instance_name>_peg_queue_<destination>

# current sequential acknowledge number (used with protocol taip and ack=seq), use 'get'
/data/app_data/__cloud_syrusjs_pegasus1_ack

# contains queued events for destinations pegasus1 and mqtt, use 'lrange'
/data/app_data/__cloud_syrusjs_peg_queue_pegasus1
/data/app_data/__cloud_syrusjs_peg_queue_mqtt

# signals and values for all components, use 'hgetall', 'hget'
/data/app_data/__cloud_syrusjs_signals

# boolean state of custom signals, use 'hgetall', 'hget'
/data/app_data/__cloud_syrusjs_signals_states

Examples

# Get the last ACK value
$ redis-cli get /data/app_data/__cloud_syrusjs_pegasus1_ack

# Get the oldest event from a queue
$ redis-cli lrange /data/app_data/__cloud_syrusjs_peg_queue_pegasus1 -1 -1

# Get all signals and values for a syrusjs instance
$ redis-cli hgetall /data/app_data/__cloud_customsignal_signals

# Getting the value of a signal
$ redis-cli hget /data/app_data/__cloud_syrusjs_signals_states isON
"true"

# make sure to escape $ with \ in front when using redis-cli via terminal
$ redis-cli hget /data/app_data/__cloud_syrusjs_signals \$net_wifi.ip_address
"192.168.1.148"

Debugging

Here are some helpful tips that can help you debug your SyrusJS script.

• use send event to generate an event and send it to the destinations

send event event_definition

• use fire signal to simulate the activation of a signal

fire signal signal_name

• SyrusJS uses the SDK (opens new window) which means it's redis in the background, thus you can monitor the communication of all the device components and debug data this way

redis-cli monitor | grep 'ecu'

• it may be useful to do some logging internally first before you send any payload to a destination

define destination logger file:///data/app_data/syrusjs/output.log

• if you're stuck on a trigger boolean logic, use the device's outputs as signals as these are user manipulated

define event my_event trigger=out1,out2,and,out3,out4,and,or

• you can view older output & error logs for each instance of syrusjs in the /data/logs/ directory

• if your application is consuming a lot of data check the allow_ commands on the destination definition in order to limit which interface each destination is supposed to work at.