Syruslang

Intro

Syrus IoT Telematics Gateway can be programmed with a proprietary 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 example configurations checkout our Github Repo.

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

What is SyrusJS?

Syruslang runs on an embedded application inside the Syrus 4 called SyrusJS which manages a syruslang configuration file and all of its 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:

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

# comment
define command
# >[email protected]#% 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.

:::warning ⚠️
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

:::

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

:::warning ⚠️
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

:::tip 💡
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 out1 on
    set out2 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.

:::tip 💡
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 out2 on

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

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

:::

:::tip 💡
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,...]

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.

🚧

One fieldset per destination

Make sure to define one fieldset per destination you create.

configuration.syrus.confdestinations.syrus.conf

# group definitions
define group tracking
define group bluetooth

# fieldset definitions
define fieldset default fields=$gnss,$io
define fieldset btdata fields=$ecu,$net_eth

# event definitions
define event braking group=tracking ack=seq fieldset=default [email protected]_braking.signal
define event movement group=bluetooth ack=seq fieldset=btdata [email protected]

# groups destinations
set destinations group=tracking destination_peg1
set destinations group=bluetooth bt_event_destination

# multiple destinations

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

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

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 format used for Pegasus platform)
• csv used for file type destinations

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

More information about MQTT

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

://_:_ - endpoint for S4GBT Destination Point (used for broadcasting)
://apps:_ - endpoint for S4GBT User Application Console (allows acknowledgement of messages)

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

Protocol, Transport, Endpoint Support Matrix

The following table shows a relationship between the supported protocols for each transport method and their destination

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

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:

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:

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.

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

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

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.

Clearing destination queues with TAIP ack

To clear a taip destination queue you can send the command >SRT;SFBUFF< using the send-message command.

$ syrus-apps-manager send-message __cloud_syrusjs '>SRT;SFBUFF<'

🚧

HTTP Errors

In the output/error logs you may get a message: ECONNABORTED. This is a disconnection message that means that the Syrus abruptly cut the communication with the remote server. It could be due to several reasons, for example:

• Exceeded maximum timeout
• Network congestion / loss of coverage

Logging 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. By default, file destinations use the log rotation tool to automatically rotate the file that's being logged according by size and/or amount of days.

The format to create the file destination is:

define destination NAME PROTOCOL file:///PATH ACK ROTATE SIZE COMPRESS

The possible parameters to configure when defining a file destination are:

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

Example destination definition:

define destination logger csv file:///data/app_data/syrusjs/output.csv ack=disabled rotate=5D size=10MB compress=true

Once the log starts you can use a command like zip to download the file to make sure it's capturing the correct data.

# zip the output file into the /data/logs folder
# format: zip DESTINATION_PATH SOURCE_FILE
$ zip /data/logs/output.zip /data/logs/output.csv

# then download the file using Syrus Cloud
download-file /data/logs/output.zip

For more information on the signals and fieldsets possible when logging data check out the blackbox section.

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

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

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

actions

Actions related info.

adas (ecu)

ADAS accessory related info, configured via the ecu monitor.

blackbox

Blackbox functionality allows you to save data to a file.

battery

Device internal battery information.

bluetooth

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

bluetooth beacons (ble)

Bluetooth low energy that can communicate with sensors and tags.

counters

Device counters information.

destinations

Destinations related actions.

ecu

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

events

Events related actions.

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.

fuel sensor

Fuel sensor related information

geofences

Geofences related information

gnss

GNSS position information

ibutton

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

io

Inputs/Outputs component

mdt

RS-232 Mobile Data Terminal info

modem

Modem information.

net_cell

Cellular interface

net_eth

Ethernet interface

net_wifi

Wifi interface

net_wlan1 (hotspot)

Hotspot interface

people_counting

People counting camera signals, actions, and recommended fieldsets.

power_save

Power save mode

rfid

Serial RFID component

satellite (satcom/sigfox)

timers

time windows

temperature

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

tpms (ecu)

TPMS information from the engine control unit.

tracking_resolution

Tracking resolution information

variables

Variables related information

video

Video related information, more info

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

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

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.

# 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

Blackbox

Actions and Signals List

The blackbox feature allows you to save data to a file periodically. It is enabled automatically for any destination file definition. For information on how to configure the destination file see Logging to a file.

Once you create the definition in your destinations file you're ready to start saving data to it.

📘

$MEDIA_PATH and USER_PATH

Note that you can use $MEDIA_PATH or $USER_PATH to indicate /media/mmcblk0p1 or /data/users/syrus4g

For example, if you want to log data second by second to a file on an SD card and have that file automatically compress and rotate after 1 week you can use a destination like:

define destination gps_data csv file://$MEDIA_PATH/gps_data.csv ack=disabled rotate=1D

and a configuration file with:

# create a group for logging
define group blackbox

# create a fieldset to append data to the csv
define fieldset csvfields fields=gnss_timestamp:$gnss.timestamp,
    speed:$speed,
    acceleration:$gnss.acceleration.value,
    latitude:$gnss.latitude,
    longitude:$gnss.longitude,
    heading:$gnss.heading,
    bearing:$gnss.bearing,
    altitude:$gnss.altitude,
    fix:$gnss.fix,
    sats_active:$gnss.satsActive,
    accuracy:$gnss.accuracy,
    hdop:$gnss.hdop,
    vdop:$gnss.vdop,
    pdop:$gnss.pdop,
    power:$io.pwr,
    ignition:$io.ign,
    input1:$io.in1,
    $ecu.fef4,

# signals for detection of ignition
define signal sg_ignON $io.ign 
define signal sg_ignOFF $io.ign == false

# create a timer every second
define timer tm_csv duration=1sec enabled=true repeat=true

# timer conditions to start and stop based on ignition state
define action ev_startlog trigger=sg_ignON start timer tm_csv
define action ev_stoplog trigger=sg_ignOFF stop timer tm_csv

# event that's generated and saved to the file
define event ev_writelog group=blackbox fieldset=csvfields rate=1/1sec label=blackbox code=88 [email protected]_csv,sg_ignON,and

# log the events from group logs to the destination
set destinations group=blackbox gps_data

This will create files with the following format: NAME-YYYYMMDD.gz where NAME is the destination file name, so in this case gps_data.csv and YYYYMMDD is year, month, and date, example: 20220621. Note that the first file is created at midnight for the previous day.

In the previous example, logs will be created for up to 5 days and then the oldest file is rotated out.

[email protected] /media/sd_card
-rwxrwxrwx    1 root     plugdev   228.9K Jun 18 00:00 gps_data.csv-20220617.gz
-rwxrwxrwx    1 root     plugdev   164.7K Jun 19 00:00 gps_data.csv-20220618.gz
-rwxrwxrwx    1 root     plugdev   175.2K Jun 20 00:00 gps_data.csv-20220619.gz
-rwxrwxrwx    1 root     plugdev   175.3K Jun 21 00:00 gps_data.csv-20220620.gz
-rwxrwxrwx    1 root     plugdev   175.4K Jun 22 00:00 gps_data.csv-20220621.gz
-rwxrwxrwx    1 root     plugdev     7.9M Jun 22 19:04 gps_data.csv

Once the files are generated you can use the download file feature in SyrusCloud to download the logs remotely at any time.

Bluetooth

Actions and Signals List

Bluetooth allows you to pair and connect to a bluetooth speakerphone that support HFP bluetooth profiles 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

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

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

Bluetooth 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 [email protected]

# 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 [email protected]

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

Bluetooth beacons

Actions and Signals List

Once you have configured a bluetooth BLE sensor, you can trigger signals and detect states in the following way:

Signals

States

The next script send events when detect a change in the temperature

# -- Variables definitions
define variable movement
set variable movement 0

define variable temperature
set variable temperature 0

# -- Fieldsets - add $ble to enable taip  or json fieldset
define fieldset default fields=$io,$ble

# -- Signals - Used prevously defined alias "Kitchen"
define signal sg_hightemp $ble.Kitchen.temperature > 20
define signal sg_lowtemp  $ble.Kitchen.temperature <= 20
define signal sg_movement $ble.E7973F682A94.movement > {{$variables.movement}}

# -- Events - trigger only used on the action
define event ev_hightemp group=tracking ack=seq label=hitemp code=70 fieldset=tracking
define event ev_lowtemp group=tracking ack=seq label=lotemp code=71 fieldset=tracking
define event ev_tmpchg group=tracking ack=seq label=tmpchng code=73 fieldset=tracking
define event ev_movement group=tracking ack=seq label=mvnt code=74 fieldset=tracking

# -- Actions
define action ac_hightemp trigger=sg_hightemp
  set variable temperature {{$ble.Kitchen.temperature}}
  send event ev_hightemp
  speak "High temperature detected at {{$variables.temperature}}"

define action ac_lowtemp trigger=sg_lowtemp
  set variable temperature {{$ble.Kitchen.temperature}}
  send event ev_lowtemp
  speak "Low temperature detected at {{$variables.temperature}}"

define action ac_tempchng [email protected]
  set variable temperature {{$ble.Kitchen.temperature}}
  send event ev_tmpchg
  speak "Temperature change to {{$variables.temperature}}"

define action ac_movement trigger=sg_movement
  set variable movement {{$ble.E7973F682A94.movement}}
  send event ev_movement
  speak "Movement detected at {{$variables.movement}}"

Counters

Actions and Signals List

Syrus has built-in counters that include counts for common metrics such as:

• Total Distance Traveled
• Total Ignition ON Time
• Total Time While Idling
• Total Time Overspeeding
• etc...

Syrus can also build counters based on custom signals, these can be used to count the:

• Number of times a signal occurred
• Accumulated time (total time) in seconds
• Difference in time since last event (delta)
• Traveled distance (total distance) in meters
• Difference in distance since the last event (delta)

Create Built-in Counter

To create a counter that uses the built-in metrics you can define it as follow:

define counters name

This automatically creates an internal count of the following fields.

Initializing
By default, these fields start at 0 but can be initialized from any value on the first time it's defined.

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

🚧

Initialize counters

Note that once counters are initialized they can't be modified with the same definition.

configuration.syrus.conf

# initialize counters
define counters globals odometer=0 
   ignition_time=0 
   idle_time=0 
   over_speed=0 
   over_rpm=0 
   hard_brakes=0 
   harsh_fwd_acceleration=0

to modify use the set commands

You can initialize the values of the counters like this:

# odometer of 23405km and hourmeter of 9502hrs
define counters name odometer=23405000 ignition_time=34207200

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

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=80 rpm_threshold=3500 begin_idle_time=3

Modify thresholds

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

set counters name field=value

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

Create Custom Counter

When you create a counter for a custom signal Syrus will automatically create an internal count of the following fields.

To create a signal counter you just need to define the signal, then create the counter:

# start by defining the signal 
define signal sg_in1_on $io.in1

# create a counter for this signal
define counters input1_counts signal=sg_in1_on start=true

Fieldset

The fieldsets can be defined with

field_name:$counters.name.field

# built-in counters for "driver1"
define counters driver1 odometer=50925

# fieldset for driver1
define fieldset driver_1 fields=
    distance:$counters.driver1.odometer,
    ignition:$counters.driver1.ignition_time

#########

# custom counters for signal: input1_counts
define counters input1_counts signal=sg_in1_on start=true

# fieldset for input1 
define fieldset input1_fieldset fields=
    total_in1_count:$counters.input1_counts.total_count,
    total_in1_duration:$counters.input1_counts.total_time,
    total_in1_distance:$counters.input1_counts.total_distance

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

define fieldset peg fields=
    VO:$counters.driver1.odometer,
    CE:$counters.driver1.ignition_time,
    CV00:$counters.driver1.hard_brakes,
    CV01:$counters.driver1.harsh_fwd_acceleration,
    CV02:$counters.input1_counts.total_count,
    CV03:$counters.input1_counts.total_time,
    CV04:$counters.input1_counts.time_increment,
    CV05:$counters.input1_counts.total_distance,
    CV06:$counters.input1_counts.distance_increment

Actions

The following actions can be performed over counters:

The format is:
action counters name

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

## Built-in Counter Example

# start counters when signal john_connected is detected
define action trigger=john_connected start counters john

# stop counters when signal john_connected is not detected
define action trigger=john_connected,not stop counters john

## Custom Counter Example

# stop custom counter
define action ac_stop_in1_count trigger=sg_in1_count stop counters input1_counts

Signals

You can define signals with the counter values as follow:

## Built-in Counter Example

# signal when the ignition_time reaches 200 hours
define signal hourmeter200 $counters.john.ignition_time > 720000

# signal when the odometer reaches 20km
define signal odometer20km $counters.john.odometer > 20000

# fire respective events
define event hourmeter group=default fieldset=default ack=seq label=200hr code=25 trigger=hourmeter200
define event odometer group=default fieldset=default ack=seq label=20km code=25 trigger=odometer20km

## Custom Counter Example

# signal when a value is reached
define signal sg_input1_duration_limit $counters.input1_counts.total_time >= 60

# signal when number of times is >= 10
define signal sg_input1_amount_of_times $counters.input1_counts.total_count >= 10

Head to the deploy section to see an example showcasing the counters with HoS.

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 from the SDK, if the parameter name is not listed then you'll always have the option to use the $id.

Signals

Signals can be constructed in 2 main ways, either using the name of the parameter along with an operator and a value, or a change using delta parameter.

Using the name along with the operator and value allows you to do things like: detect when the odometer is greater than or equal to 100,000km, while the delta changes allow you to do things like: detect when the fuel value drops by 15% in 2 minutes.

Signals with operators

To construct signals in the traditional way using operators use the same convention as above, either the $name or $id from the ECU directory

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

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

# 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

Delta changes

To define signals using the deltas (changes) in values, refer to the following section in the ECU development.
It explains how to create a file that allows you to detect changes for particular parameters when the value increases or decreases by X value in Y seconds.

Assuming we have the following: ecuparams.conf.json

{
    "fefc_2": {
        "warnings": [
            "delta?time=60&value=10",
            "delta?time=120&value=-10"
        ]
    } 
}

We can trigger the signals like so:

define signal fuel_refill @ecu_warning.fefc_2.delta?time=60&value=10

define signal fuel_theft @ecu_warning.fefc_2.delta?time=120&value=-10

and trigger the accompanying events like this

define event ev_fuel_theft group=tracking fieldset=default ack=seq label=excsvfl code=90 trigger=fuel_theft

define event ev_fuel_refill group=tracking fieldset=default ack=seq label=flrfl code=91 trigger=fuel_refill

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:

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
}

DMS / 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.
For more information on video media click here.

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.

Fatigue Signals and Media Supported

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

Normal events

Diagnostic events

Compatible with Cipia FS-10 DMS only