# Syrus programming language

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.

# Github

Github Repo with snippets and config examples.


# Quick Intro

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

# SyrusJS

Syruslang runs on an embedded application 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/syrusjs/.

The important files to consider within this directory are:

Filename Description
appends.syrus.conf Any remote command sent to the device.
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 Application Manager section of the Management Tool can be used to manage the files within SyrusJS.

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

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 apx-apps can be used to interact with the application itself (start, stop, restart). Just make sure after you update the configuration to restart the application.

sudo apx-apps 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 recommended.

✅ define signal custom1
❌ 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

Note that when deleting a definition, it 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

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

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 slow min_duration=10sec $gnss.kph < 10
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 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 trigger=signal1[,signal2,operator,...] command

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 $io.out2 on

Note, the words on & off represent == true and == false respectively

For example:

define action enable_hotspot trigger=work_wifi,ignitionOFF,and set $net_wifi_hotspot.mode on

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

The event definition format is as follow:

define event event_name group [fieldset] [rate] [ack] [label] [code] trigger=signal1[,signal2,and,...]
param description default value
group is a way to group several events, we'll take a look at how this is useful later 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 enables 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 the endpoint trckpnt
code is a numeric code for the event generated (range: 0, 9999) 0
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=none 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=none label=park code=4 trigger=isON,slow,and,nomov,and

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

# Event Grouping

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

# Definition parameters

# Fieldsets

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.

# 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

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

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:

  • ://url[:port]
  • ://ip_address[:port]
  • :///path/to/file.log

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

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 acknowledgement to be used by this destination, can be

  • imei - which means the endpoint will respond with the device's IMEI in order to confirm the message
  • seq - which means the endpoint will respond with a sequential numeric ID in order to confirm the exact message sent
  • disabled - which means that the endpoint will not reply with any sort of confirmation

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

sample destination definition

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

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/connect/status"
username username for client authentication "pass"
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/events"
commands_pub topic to publish command responses "dev/commands/resp"
subscribe or commands_sub topic that handles syruslang commands "dev/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 headers param to append headers to the http connection once an event is transmitted.

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

As the device transmits the event message to the endpoint the ack param verifies if the device is expecting any sort of response from the endpoint indicating that it received the event.

The possible ack that can be configured on an event are:

  • imei
  • seq
  • none (default)

When the imei ack is configured on the event, the device expects it's own IMEI as a response to every event sent to the endpoint, this way it can send the next event in queue. If not it will keep retrying the same message.

The seq ack is a sequence id number that the device generates, starting with 1, that helps identify each individual message that's acknowledged by the endpoint. To acknowledge the reception of this message just send the seq id number back to the device.

Note if you're using an MQTT endpoint you can specify the QoS of each event with the ack

ack QoS
none 0
not defined 1
seq 2

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:

The possible interactions are:

Set or define data

define definition custom_name: define any syruslang command

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.

Retrieve data, definitions and/or values

To retrieve definitions from SyrusJS you can publish data to the commands_sub topic with the following:

Singular get definition custom_name retrieves a particular definition, for example get signal ignition_on returns the definition of that signal.

Plural get definitions retrieves all instances of that definition, for example get signals returns all signal definitions

                                                definitions description
action custom_name returns action definition of custom_name
actions returns all action definitions
counter custom_name returns counter definition of custom_name
counters returns all counters definitions
destination_state custom_name returns enable if destination is used
destination custom_name returns destination definition of custom_name
destinations returns all destinations definitions
event custom_name returns event definition of custom_name
events returns all events definitions
fieldset custom_name returns fieldset definition of custom_name
fieldsets returns all fieldsets definitions
geofence custom_name returns geofence definition of custom_name
geofences returns all geofences definitions
group custom_name returns group definition of custom_name
groups returns all groups definitions
signal custom_name returns signal definition of custom_name
signals returns all signals definitions
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 TX command: >STXmessage<

Examples:

>STXget fieldset default<

>RTXdefine 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<
>STXget signal ignitionON<

>RTXdefine signal ignitionON min_duration=2sec $io.ign;true<
>STXget value $net_wifi.ip_address<

>RTX192.168.1.205<
>STXdefine signal panic_signal $io.in1<

>RTXOK<

# System tool commands

With the exec keyword you can execute system tool commands.

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

# Features

# Accelerometer

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

# Bluetooth

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: >STX 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
>STXbluetooth scan 15<
>STXbluetooth 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
>STXbluetooth list_discovered<
>RTX{"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'

# Counters

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 >STX 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 SSID"
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)

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

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

get value device_component

get value $ecu.fee0_5-8

# Signal

The signals associated with the ECU can be found here: ECU

💡Note: that parameters with Count units are reported in numerical 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

Example ECU signals:

define signal low_fuel $ecu.fefc_2 < 10
Signal Description
$ecu.feee_1 > 100 True when the coolant temperature is > 100°C
$ecu.feef_3 < 20 True when the oil level is below 20%
$ecu.fef7_5-6 < 8 True when the vehicle battery is < 8V
$ecu.e000_4.7 == 1 True when the the seat belt is buckled

# 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.f004_4-5
{
  ...
  "fuel_level": 80,
  "rpm": 1430
}

# Geofences

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

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

# Power Save Mode

The power save mode allows you to put the device in a low power consumption mode, which can help save a vehicle's battery. By default the device enters the low power consumption or power save mode after 5 minutes of no ignition being detected.

# Set

You can set the power save mode with the following command:

set power_save option

option Description
immediate Orders the device to enter Power Save Mode with the previously loaded configuration. If no previously loaded configuration is found it uses the default described above.
mode Must be followed by PSM_string and the only valid format is "sleep_condition;wakeup_condition;wait_time".

For more information on creating the PSM_string visit the apx-psm tool.

For example, if you want to order the device to go into power save mode immediately, use

set power_save immediate

This example orders the device to go into power save mode after 3600 seconds (1hr) of no Motion and No Ignition, it will wake up if it detects Input 2 ON, or Ignition, or Motion, or every 240 minutes (4hrs) for 300 seconds (SLP:300). Once it wakes up the counters reset and the device will monitor the sleep conditions again it will go back to sleep according to the wait_time

set power_save mode "MOT:0,IGN:0,SLP:300;IN1,IGN,MOT,MIN:240;3600"

# 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

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

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

Temperature can be read via the onewire (1-wire) cable and compatible temperature sensor accessory. 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 91000014A0707F01

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

# Tracking Resolution

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.

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

define tracking_resolution standard 30deg 60sec 500mts
define tracking_resolution elite 10deg 20sec 100mts
define tracking_resolution distance 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

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

# Configuration walkthough

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

# 1. Create the signals for the events

  • 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 track_res_ignon 45deg 60sec 500mts
define action action_stop_ignon trigger=signal_ign_off set track_res_ignon 0deg 0sec 0mts

define action action_start_ignoff trigger=signal_ign_off set track_res_ignoff 0deg 120min 0mts
define action action_stop_ignoff trigger=signal_ign_on set 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 fieldset

  • Since we're going to report via TAIP on Pegasus, you're going to want to use the $io and $gnss fields, so Pegasus can receive the inputs/outputs and gnss data on every event.
define fieldset fieldset_default fields=$io,$gnss

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

# 7. Create the destination

  • Until now, steps 0-6 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 endpoint of your Pegasus Gateway

# 8. 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 track_res_ignon 45deg 60sec 500mts
define action action_stop_ignon trigger=signal_ign_off set track_res_ignon 0deg 0sec 0mts

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

# group
define group group_default

# fieldset
define fieldset fieldset_default fields=$io,$gnss

# 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

# 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
  • SyrusJS uses the SDK 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.

# DEVICE COMPONENTS

# 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

# 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

# battery

Device internal battery information.

property use type description
$battery fieldset Object json appends all accelerometer fields
$battery fieldset String taip compatible field
$battery.connected fieldset,signal Boolean True if the internal battery is connected
@battery.critical signal Number Battery < 5%
@battery.low signal Number Battery < 15%
$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

# 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.pgn_start_position fieldset, signal Number Value of the particular ecu variable

# events

Events related actions.

property use description
send event event_name action Generate an event to the defined destinations

# 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
$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
$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
$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, signal Number dddd, MMMM D, YYYY h:hh A format
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 out# on** action activate output #
set out# off** action deactivate output #

# 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
$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")
speak 'hello world' action String 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 port 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

# 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
$net_wifi.tx_bytes fieldset, signal Number Bytes transmitted

# 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 String Force start power save mode
set power_save mode PSM_STRING action Modify power save mode

# 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

# 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
Last Updated: 1/15/2021, 4:45:42 PM