System Tools
Apex core system tools
The Syrus 4 system tools are applications that are in charge of enabling/disabling and resetting specific hardware functionalities. They can also be used to interact with some Linux applications such as hostapd
which is used for bringing up a hotspot. And finally the tools serve as a way to create functionalities such as tracking criterias, geofences and more, which is useful for fleet management.
These applications are accessed via the shell with apx-
as a command prefix.
The standard response of these system tool command is JSON, thus you may find it useful to use jq to get a specific result.
# returns the last gps point
$ sudo apx-gps state | jq .LATEST_POINT
{"lat":25.945318,"lon":-80.452825,"alt":12.492,"speed":0.019,"heading":0,"epoch":1607006801}
# returns the first 5 geofences in the namespace applications
$ sudo apx-geofences getstatus applications | jq '.[0:5]'
# returns the name of all the geofences in the namespace applications
$ sudo apx-geofences getstatus applications | jq '.[] | {name: .geo_name}'
Result codes (Linux exit codes)
They can be consulted by echoing the Linux exit status code $?. The most common result codes are:
- 0: Action executed successfully with no errors
- 1: Catchall for general errors
- 2: Misuse of shell builtins (according to bash documentation)
- 22: Invalid argument
- 90: Response too long
- 126: Command invoked cannot execute
- 127: Command not found
- 128: Invalid argument to exit
- 128+n: Fatal error signal “n”
- 130: Script terminated by Control-C
- 255+: Exit status out of range
Sudo privileges
Note that all apx commands require special privileges, thus you must use
sudo
to execute them.
Accelerometer
apx-imu
Inertial measurement unit manager for the accelerometer and device's gyroscope. This tool calibrates the accelerometer and sets it's event thresholds.
apx-imu <command> [<args=value>]
command | description |
---|---|
configure [OPTIONS] | Set the driver behavior thresholds in milliG units. |
calibrate [OPTIONS] | Start the device calibration procedure. Take into account that the vehicle must be stopped/stationary on a level surface when starting this process. |
test | Starts the accelerometer self-test. If second parameter is not used it returns the motion state. It forces some of the events (motion, collision, hard_braking, etc) to be triggered. |
status | Returns the list with all the configured parameters. |
events | Returns the list with the last 25 acceleration events. |
Use the following options to set/get the different parameters related to the accelerometer. If the second argument is not specified, it returns the value configured
Calibration Options
options | description |
---|---|
--status | Set to start or stop to start and stop the calibration procedure |
Configuration Options
options | description |
---|---|
motion_threshold | From 10 to 500, Default: 30 (30*1milli-g=30milli-g) |
motion_duration | From 1 to 8, Default: 2 (2*0.5=1sec) |
front_collision | From -1000 to -15000, Default: -2000milli-g |
back_collision | From 1000 to 15000, Default: 2000milli-g |
right_collision | From -1000 to -15000, Default: -2000milli-g |
left_collision | From 1000 to 15000, Default: 2000milli-g |
harsh_acceleration | From 200 to 600, Default: 260milli-g |
hard_braking | From -200 to -600, Default: -260milli-g |
cornering_right | From -200 to -600, Default: -400milli-g |
cornering_left | From 200 to 600, Default: 400milli-g |
The alignment process can be found in the CONNECT page.
Accelerometer parameters
Note that the self_alignment procedure is required in order to trigger any acceleration related signal with Syruslang.
Query status of alignment procedure
# Configure the hard braking threshold to -240 milli-g and cornering left to 350 milli-g
$ apx-imu configure --hard_braking=-240 --cornering_left=350
# Start the calibration process
$ apx-imu calibrate --status=start
The device will return one of these states
ALIGNMENT_CURRENT_STATE | % completed | description |
---|---|---|
1 | 1% | Deleting previous alignment data |
2 | 10% | Waiting for GNSS signal |
3 | 30% | Running initial stage. Computing recorded data |
4 | 50% | Running second stage. Waiting for GNSS signal |
5 | 70% | Waiting for vehicle speed to go over 30kph |
6 | 80% | Waiting for a valid braking event |
7 | 90% | Braking event detected. Computing recorded data |
8 | 100% | Alignment process done |
Examples:
# Start the self alignment process:
$ apx-imu calibrate --status=start
# Configure the hard braking to -240 milliG and cornering left to 350 milliG:
$ apx-imu configure --hard_braking=-240 --cornering_left=350
# Read the value of the harsh forward acceleration threshold:
$ apx-imu CFG_HARSH_FWD_ACCELERATION
# Read the list of parameters configured:
$ apx-imu config_list
{"MOTION_THRESHOLD":30,"CFG_FORWARD_COLLISION":-2000,"CFG_BACKWARD_COLLISION":2000,"CFG_LAT_COLLISION_FROM_RIGHT":-2000,"CFG_LAT_COLLISION_FROM_LEFT":2000,"CFG_HARSH_FWD_ACCELERATION":260,"CFG_HARD_BRAKING":-260,"CFG_CORNERING_RIGHT":-350,"CFG_CORNERING_LEFT":350}
Applications
syrus-apps-manager
Install, run, and manage applications on the device.
syrus-apps-manager [option] [argument_1] [argument_2] [argument_3]
Syrus application manager
The command
syrus-apps-manager
does not requiresudo
in front and can be run by usersyrus4g
option | description |
---|---|
help | Prints this help message |
install-app | install an app from .zip file on the device, makes it available to create instances, takes as argument_1 the path where the zip file exists |
update-app · download-app | download a new version of the app from the repository declared for the app, takes as argument_1 the name of the app and argument_2 the new version to download, if argument_2 is omitted it will try to download the stable version if available |
list-apps | list the available apps installed on the device |
delete-app | delete an app on a specific version, takes as argument_1 the app and argument_2 the version of the app |
check-updates | checks for updates on every app thats exposes a repository on the manifest |
list-instances | list all the instances of apps running on the device |
create-instance | create an instance from a previously installed app on the device, argument_1 is the name of the instance, argument_2 the name of the app, and the argument_3 the version |
update-instance | update an instance to a different version, takes as argument_1 the name of the instance and argument_2 as the version |
delete-instance | delete an instance, takes as argument_1 the name of the instance |
start · stop · restart | start,stop or restart one instance, takes as argument_1 the name of the instance |
get-running | return a list of only running instances |
status | return the status of one instance, takes as argument_1 the name of the instance |
send-message | Send a message (via nc) to applications that expose a unix socket. |
start-shell | Start a shell (via nc) with applications that expose a unix socket. |
Instance naming
Note that instances must start with lowercase, and contain no spaces or special characters.
Examples:
# Manual application installation from source
$ cd /data/downloads
$ wget https://server.com/applications/customApp/1.0.0.zip
$ syrus-apps-manager install-app customApp /data/downloads/1.0.0.zip
# SyrusJS example installation
$ wget https://syrus4.dctserver.com/apex/applications/syrusjs/1.34.1.zip -O /data/downloads/1.29.1.zip
$ syrus-apps-manager install-app /data/downloads/1.34.1.zip
$ syrus-apps-manager create-instance test_instance syrusjs 1.34.1
$ syrus-apps-manager start test_instance
# Update syrusjs application
$ syrus-apps-manager update-app syrusjs 1.34.0
# Update an instance of syrusjs
$ syrus-apps-manager update-instance my_syrusjs_instance 1.34.0
# Send commands to a syrusjs instance
$ syrus-apps-manager send-message __cloud_syrusjs 'get signal_value isON'
signal value=true
# if sending the command locally make sure to use single quotes ' around commands with special characters
$ syrus-apps-manager send-message __cloud_syrusjs 'get value $net_wifi.ip_address'
192.168.1.148
# if sending a command via syrus-cloud or MDT you must use double quotes " and escape special characters
$ syrus-apps-manager send-message __cloud_syrusjs "get value \$net_cell.connected"
true
# Start a shell with syrusjs
$ syrus-apps-manager start-shell __cloud_syrusjs
get signals
define signal ...
Audio
apx-tts
Tool to convert text to speech in different languages. Use the apx-bt tool to pair to a compatible bluetooth device first.
apx-tts [language] [message]
language | description |
---|---|
en-US | English |
en-GB | Great Britain |
de-DE | German |
es-ES | Spanish |
fr-FR | France |
it-IT | Italian |
[message]
is the actual message to say
Examples
$ apx-tts en-US 'Testing text to speech'
$ apx-tts es-ES 'Una prueba de texto a voz'
Bluetooth
apx-bt
Bluetooth tool with BLE functions and pairing with compatible with bluetooth headsets. If you're looking for the text to speech function, check out the apx-tts tool.
apx-bt [<action>] [--arguments]
Actions
action | description |
---|---|
help | Returns this message. |
on | Will enable the Bluetooth module. |
off | Will disable the Bluetooth module. |
status | Will display core application version, prioritized audio, device MAC, device name, and the mode configured. |
scan | Followed by --time in seconds. Application will scan for nearby devices for up to 30 seconds. |
pair | Followed by --mac . Will begin the pairing process with the device. Device needs to have been previously scanned. |
pair_forced | Followed by --mac . Will force a pair process with the device. |
connect | Followed by --mac . Attempt a connection with a previously paired device |
unpair | Followed by --mac . Will unpair a previously paired device. |
disconnect | Followed by --mac . Will disconnect a previously connected device. |
switch_audio | Followed by --mac . Will declare the device to be the main source of audio. |
info | Followed by --mac . Will display information about the device. |
info_all | This will display information about all of the recently discovered devices, if those devices are paired, or if they are paired and connected. |
history | This will display information about all of the devices that were discovered by the scanning process since last activation of the Bluetooth module |
list_discovered | Returns the list of all the devices that have been discovered by the scanning process. Note: A device might be scanned and added to the list of paired devices but not appear in the list of discovered devices. Recommended to check both lists. |
list_connected | Returns the list of all paired and connected devices. |
restart | This will restart the application module. |
reset | This command resets everything regarding the application. All information about the devices, connections, and pairs will be lost. |
routed_audio | This will display the address of the device producing audio. |
soc_audio | Routes prioritized audio device to allow audio from SOC. |
mdm_audio | Routes prioritized audio device to allow audio from MDM. |
arguments | description |
---|---|
--mac | Device MAC address. A single string of hexadecimal is expected for the device |
--time | Time in seconds |
Switch audio
Note that the
switch_audio
action is only relevant when you have multiple compatible speakers paired to the Syrus, and you want to switch which speaker to use to playback an audio without having to disconnect them.
Examples:
# Start a scan for nearby bluetooth devices for 15 seconds.
$ apx-bt scan --time=15
# List discovered Bluetooth devices after scanning
$ apx-bt list_discovered
{"C83432DA6A1C":"Family Room TV","000664EDF530":"CricutAIR2-F530","E8ABFB463615":"Boltune BT-BH010","84A444220FA2":"[TV]Samsung LED55"}
# Pair to a discovered bluetooth device with the MAC address: 02:06:EF:66:43:0A
$ apx-bt pair --mac=0206EF66430A
BLE Actions
$ apx-bt [<action>] [--arguments]
action | description |
---|---|
advertising | Followed by desired parameters to enable or disable advertising, which type of advertising to do, and for how long to advertise (--mode , --flag , and --duration respectively). If not followed by anything it shows the parameters used. |
auth | Followed by the password. Only usable from the BLE device that is connected. |
change_auth | Takes two arguments. The --old_pass and the --new_pass that BLE devices must use for authentication. Passwords must be of 1 to 30 characters long and cannot contain spaces. Only 0-9,a-z,and A-Z characters are allowed. |
send | Followed --characteristic and --message . This command takes two arguments where the first argument is the characteristic to notify and the second argument is the message to send to the device that is subscribed for notifications. The message can be any NULL terminated string. Refer to Valid Characteristics. |
ping | Used for maintaining a keep alive communication between a BLE device and this unit. Will return "pong". |
change_name | Followed by --name . Will change both the Bluetooth name of the device and the BLE name being advertised by the device. The name will always be prefixed with Syrus 4G . The name can be up to 15 alphanumeric characters. |
ble_status | Not followed by any arguments. Will display a list of all BLE devices that are currently connected or recently disconnected. |
Advertising
arguments | description |
---|---|
--mode | Either 0 or 1 for disable and enable respectively. |
--flag | To get the desired on state flag, simply add the hex numbers from Number on the Advertising Table below. |
--duration | A value in seconds between 30 to 300 seconds. A number more than 300 will force advertising duration to be 600 which means advertising is continuous, meaning advertising will always be on. |
Advertising Table:
Number | Not added | Added |
---|---|---|
0x001 | Local Random Address | Local Public Address |
0x002 | Non Discoverable | Discoverable |
0x004 | Non Connectable | Connectable |
0x010 | Advertise Name Off | Advertise Name |
0x020 | Advertise Tx Pwr Off | Advertise Tx Pwr |
0x040 | No Appearance | Advertise Appearance |
0x100 | Peer Random Address | Peer Public Address |
Valid Characteristics:
characteristic | Description |
---|---|
events | To be used for events that occurred |
user_apps_console | To be used by internal user applications that wish to communicate with external user applications. |
Examples:
# Advertising is enabled, discoverable (`0x002`), connectable (`0x004`), and the name is advertised (`0x010`) for 200 seconds.
$ apx-bt advertising --mode=1 --flags=0x16 --duration=200
# Send a json string to the events
$ apx-bt send --characteristic=events --message={"name":"Joe"}
Bluetooth Beacon
This tool lets you read and configure the BLE scan engine
$ sudo apx-bbs help
$ apx-bbs <command> [<args=value>]
Actions
action | description |
---|---|
status | Returns the last scanned devices. |
set [options] | Used to configure the service parameters like the scan_time. |
add [options] | Add or modify a BLE device to the white list. |
remove [options] | Removes a BLE device form the white list. |
get [options] | Reads the alias of a device given a MAC address. |
get_config | Reads the configuration of the bluetooth beacon settings. |
get_all | Returns all the BLE devices added to the white list. |
version | Returns the tool version. |
enable | Enable the syrus bluetooth beacon service (default) |
disable | Disable the syrus bluetooth beacon service |
help | Print this help. |
Arguments
arguments | description |
---|---|
-s, --scan_time | The BLE channels scanning time this determine the update time (default 10s). |
-m, --mac | The mac address of the BLE device. |
-a, --alias | The desired alias of the BLE device. |
-e, --enabled | Enable or disable the loggin service |
Examples:
# Check the last scanned devices:
$ apx-bbs state
# Configure the scanning time in seconds:
$ apx-bbs set --scan_time=60 --enabled=true
# Add a new ble device to the whitelist:
$ apx-bbs add --mac=AABBCCDDEEFF --alias=Refrigerated_truck
# Remove a ble device from the whitelist:
$ apx-bbs remove --mac=AABBCCDDEEFF
# Get information about the devices:
$ apx-bbs get --mac=AABBCCDDEEFF
$ apx-bbs get_all
Counters
apx-counter
Start device counters for ignition, distance and other metrics.
apx-counter [action] [namespace]
apx-counter [action] [namespace] [key] [value]
action | description |
---|---|
start | Must be followed by namespace. Will start the desired namespace. Creates it if it doesn't exist. |
stop | Must be followed by namespace. Will stop the desired namespace. |
reset | Must be followed by namespace. Will stop the desired namespace and resets the counter key values. |
resetall | Same as above only that thresholds are reset to default values. |
set | Must be followed by namespace key value. Key has its value set to value. |
get | Must be followed by namespace key. Will return the value of the key. |
getall | Must be followed by namespace. Will return the value of all of the keys. |
delete | Must be followed by namespace. Will delete the namespace. |
list | Not followed by anything. Will list information about all known counters. |
help | Prints this help message |
key | description |
---|---|
ODOMETER | Distance traveled in meters with ignition on. |
IGNITION_TIME | Total time ignition has been on in seconds. |
IDLE_TIME | Total time ignition has been on in seconds with no distance traveled after the time defined in BEGIN_IDLE_TIME. |
OVER_SPEED | Total time in seconds that the speed has exceeded the threshold value defined in SPEED_THRESHOLD |
OVER_RPM | Total time in seconds that the RPM has exceeded the threshold value defined in RPM_THRESHOLD |
HARD_BRAKES | Total number of hard brakes produced. |
HARSH_FWD_ACCELERATION | Total number of harsh accelerations produced. |
DISTANCE | The distance traveled in meters with no ignition. |
RPM_THRESHOLD | Key to define an RPM value that the vehicle must exceed to begin incrementing OVER_RPM |
SPEED_THRESHOLD | Key to define a speed value (km/h) that the vehicle must exceed to begin incrementing OVER_SPEED |
BEGIN_IDLE_TIME | Key to define how long to wait in minutes before incrementing IDLE_TIME. Default 5 minutes |
The namespace can be up to 50 characters long with no spaces. We recommend you define a schema: type:name:counter
like driver:john:0
Examples:
# start custom counter
$ apx-counter start custom1
# set the speed threshold to 100km/h for custom1
$ apx-counter set custom1 SPEED_THRESHOLD 100
# get all the values of custom1 counters
$ apx-counter getall custom1
ECU
apx-ecu
Tool to configure and read data from a vehicle's onboard computer using the CAN Bus.
apx-ecu [<action>] [--arguments]
action | description |
---|---|
configure | This may take two arguments to configure the desired CAN interface at the desired baud rate, one argument to configure the read mode of the specified interface, or no arguments. The valid arguments are --interface and --interface_mode , where --interface is the interface to configure and --interface_mode is the desired mode for that interface. A singular argument must be used to configure the read mode; this argument is --read_mode . Read mode refers to allowing ECU monitor to read data when vehicle ignition is off. When no arguments are used, this will return the current configuration used by the ECU monitor. |
listen_mode | This may take one or no arguments. This will force ECU monitor to not send data to the specified interface. The valid argument is --listen_mode . If no argument is given then this will return the current listen_mode being used. |
list_parameters | Not followed by any arguments. Returns a JSON of all the parameters read with the unique id and value. |
log | This takes three arguments. The valid arguments are --log_time , --file_name , and --log_interface . Where --log_time is the time in seconds starting from 1 second up to 40 seconds to save to the log file --file_name from the --log_interface . The file name is a relative file path name and only letters and numbers are allowed for the file name up to 20 characters long. All logs are saved in /data/users/syrus4g/ecumonitor/ecu_logs/ . |
stop | Not followed by any arguments. Halts operation of ecumonitor until it is reconfigured; this will make the configuration section from ecumonitor.conf obsolete. |
restart | Not followed by any arguments. Restarts the ecumonitor. |
clear | Not followed by any arguments. Will clear any previous returned by list_parameters command. |
version | Not followed by any arguments. Will return the version of this tool and the version of the ecumonitor core application. |
decode | This may take two arguments. The valid arguments are --unique_id and --value . This will decode the --value from the --unique_id returning a different JSON based on the unique_id to decode. If no arguments are passed then the list of valid unique_ids will be printed. |
help | Returns this help message. |
Arguments | description |
---|---|
configure | [--interface=<interface>] [--interface_mode=<interface_mode>] or [--read_mode=<read_mode>] |
listen_mode | [--listen_mode=<listen_mode>] |
log | [--log_time=<time_in_seconds>] [--file_name=<file_name>] [--log_interface=<interface>] |
decode | [--unique_id=<unique_id>] [--value=<value>] |
Valid interface |
---|
PRIMARY_CAN |
SECONDARY_CAN |
Valid interface_mode |
---|
J1939_250KBPS |
J1939_500KBPS |
ACCESSORIES_ XXXYBPS |
DISABLED |
Note: Where XXX is the baud rate and Y is either K
(Kilo) or M
(Mega).
Valid listen_mode |
---|
NONE |
PRIMARY_CAN |
SECONDARY_CAN |
PRIMARY_N_SECONDARY |
ALL |
Examples:
# Configure the primary ECU cables to work with J1939 @ 250 KBPS
$ apx-ecu configure --interface=PRIMARY_CAN --interface_mode=J1939_250KBPS
# Set the listen only mode for SECONDARY CAN
$ apx-ecu listen_mode --listen_mode=SECONDARY_CAN
# Decode a J1939 data trouble code*
$ apx-ecu decode --unique_id=feca_3-6 --value=2114126001
{"spn":177,"fmi":3,"cm":0,"oc":126}
# *Note this requires the definition of PGN: `feca` start_position: `3-6` in your ecumonitor.conf
# Perform a candump for 40 seconds from 2 CAN interfaces
$ apx-ecu restart
$ apx-ecu clear
$ apx-ecu configure --interface=PRIMARY_CAN --interface_mode=J1939_500KBPS
$ apx-ecu configure --interface=SECONDARY_CAN --interface_mode=J1939_250KBPS
$ apx-ecu log --log_time=40 --log_interface=PRIMARY_CAN --file_name=logTruck500.log
$ apx-ecu log --log_time=40 --log_interface=SECONDARY_CAN --file_name=logTruck250.log
$ apx-ecu list_parameters
# Note that underscores are not allowed for the name of the log file
# clear and list ecu parameters
$ apx-ecu clear
$ apx-ecu list_parameters
Ethernet
apx-ethernet
Manage the ethernet interface on the device. Allows you to configure DHCP mode or other network configuration.
apx-ethernet <command> [<args=value>]
commands | description |
---|---|
restart | Use this option for restarting the ethernet interface |
status | Returns the current state of the ethernet interface |
set [OPTIONS] | Returns the current state of the ethernet interface |
version | Returns the tool version |
help | Prints this help message |
options | description |
---|---|
-r, --route | Use this option for forwarding the ethernet traffic to another interface, it allows the connected device to have internet access by specifying the output interface. Valid values are: wlan0 , ppp0 (Mobile network), both , and none . |
-i, --ip | Use this option for changing the interface IP address and mask |
-g, --gateway | Use this option for changing the gateway address |
-d, --dns | Use this option for changing the dns address |
-s, --dhcp | Use this option for enabling the DHCPServer on this interface. So, when a device is connected to the device ethernet, it assigns an IP address to the connected devices. |
-f, --default | By using this option the ethernet IP address is assigned by the network. |
Examples:
# Uses the IP address assigned by the network
$ sudo apx-ethernet set --default
# Configure the ethernet in DHCP mode
$ sudo apx-ethernet set --dhcp
# Set the IP address of the ethernet interface
$ sudo apx-ethernet set --ip=192.168.5.5/24
# Configure the ethernet network with dhcp enabled
$ sudo apx-ethernet set --ip=192.168.5.1/24 --gateway=192.168.5.255 --dns=8.8.8.8 --dhcp --route=none
# Where: 192.168.5.5/24 = Device IP/Mask
# 192.168.5.255 = Gateway address
# 8.8.8.8 = DNS
# yes = DHCP server enabled
# none = Traffic is not routed to another interface
# Route ethernet traffic to both wlan0 and ppp0 interface
$ sudo apx-ethernet --route=both
# Restart the ethernet inteface
$ sudo apx-ethernet restart
# Check the ethernet status
$ sudo apx-ethernet status
{"state":"Enabled","mac":"9C:1D:58:3D:5A:90","ip":"","bcast":"","mask":"","rx_bytes":"0","tx_bytes":"0","routing":"both"}
Geofences
apx-geofences
Tool that adds and removes geofences on the device. Note that a maximum of 3000 geofences can be saved as of apex version 20.12
Add a geofence
apx-geofences add [namespace] [group] [type] [name] [radius] [lon,lat] [...]
$ apx-geofences add places parks circular country_village_park 100 -80.305340,25.943784
parameters | description |
---|---|
namespace | Name of the namespace. If no namespace, specify an empty string "" . Max 30 characters |
group | Name of the group. If no group, specify an empty string "" . Max 30 characters, min 3 characters |
type | Type of geofence. Must be circular or poly |
name | Name of the geofence. Max 50 characters |
radius | Optional Radius of the geofence in meters, required for circular geofences. Min 50 meters. Max 20000 meters. |
lon,lat | Longitude and latitude coordinates in the format decimal degrees: -80.3471745,25.917071. Max 500 pairs of coordinates. Minimum of 3 pairs of coordinates for a poly type geofence |
Remove a geofence
apx-geofences remove [namespace] [group] [name]
$ apx-geofences remove places parks country_village_park
Remove all geofences of a namespace
apx-geofences remove [namespace]
$ apx-geofences remove places
Get a list of all namespaces that exist
$ apx-geofences getns
["places","shopping_malls"]
To get all the information of the geofences of a specific namespace
apx-geofences getall [namespace]
$ apx-geofences getall places
[{"namespace":"places","group":"group","geo_name":"norman_jean","type":"poly","n_vertices":4,"vertices":["-80.33352400,25.93546900","-80.32843900,25.93494800","-80.32832100,25.93337500","-80.33331000,25.93355800"]}]
where:
namespace
: Name of the namespacegroup
: Name of the groupgeo_name
: Name of the geofencetype
:poly
orcircular
radius
: Radius of circular geofence in metersn_vertices
: Number of lon,lat pairs in the geofencevertices
: Lon,lat pairs
To count the number of geofences that exist in namespace[s]
apx-geofences count [namespace]
$ apx-geofences count places
4
To get the current state of each geofence of a specific namespace
apx-geofences getstatus [namespace]
$ apx-geofences getstatus places
[{"group":"parks","geo_name":"country_village_park","is_inside":false,"time":1623959290}]
where:
group
: Name of groupgeo_name
: Name of geofenceis_inside
: True if device is currently inside the geofence
Get Status of Geofence Inside
Note that if you create a geofence around the location of your device the
getstatus
command will return that it'sis_inside: true
.
To get the current version of the tool
$ apx-geofences version
{"version": "0.0.5"}
RETURN_CODES | description |
---|---|
0 | OK |
22 | Invalid argument |
80 | Max number of geofences reached |
81 | Geofence not found |
82 | Missing parameter |
127 | Unknown command |
Example:
# Create a polygonal geofence around 25.935469,-80.333524 25.934948,-80.328439 25.933375,-80.328321 25.933558,-80.333310
$ apx-geofences add places parks poly park_norman_jean -80.333524,25.935469 -80.328439,25.934948 -80.328321,25.933375 -80.333310,25.933558
# Print the geofences that are in the namespace places
$ apx-geofences getall places
[{"namespace":"places","group":"parks","geo_name":"park_norman_jean","type":"poly","n_vertices":4,"vertices":["-80.33352400,25.93546900","-80.32843900,25.93494800","-80.32832100,25.93337500","-80.33331000,25.93355800"]}]
apx-geofences-manager
Tool to import and export geofences massively on the device.
apx-geofences-manager [option] [arguments]
option | description |
---|---|
import | Create geofences in batch using syruslang scripting command, the tool requires arguments: namespace and path. |
export | Export geofences to a single file. Accepts arguments: format, namespace, and file. |
arguments | description |
---|---|
--remove | Remove all geofences in the namespace before start importing |
--dry-run | Run command to proccess without creating geofences |
--format · -f | Format to be exported, accepted values are: syruslang,geojson |
--namespace · -n | Namespace to be export or imported |
--path · -p | Path to file destination where import geofences or path where to export destination. Must be a syrus.conf and contains syruslang script language or a .geojson with valid geojson data |
# Contents of /data/downloads/geofences.syrus.conf
# polygonal
define geofence terminal_a_1416 group=mygroup1 -80.27661,25.79784 -80.27358,25.79897 -80.27091,25.79904 -80.27083,25.79689 -80.2734,25.79728 -80.27561,25.79676 -80.27638,25.79674 -80.27661,25.79784
# circle
define geofence sample_circle_geofence_27422 group=mygroup2 radius=50mts -122.08570313535118,37.42169546752972
# Import geofences from '/data/downloads/geofences.syrus.conf' with the namespace 'myplaces' to the device.
$ apx-geofences-manager import -p /data/downloads/geofences.syrus.conf -n myplaces
# Export geofences on the device from the namespace: 'myplaces' into Syruslang format with the name: '/data/downloads/geofences_applications.syrus.conf'
$ apx-geofences-manager export -f syruslang -n myplaces -p /data/downloads/geofences_applications.syrus.conf
{"results":"ok","geofences":10}
GNSS/GPS
apx-gps
Allows you to control the GNSS/GPS interface on the device.
apx-gps <command> [<options>]
command | description |
---|---|
status | Will display the current position, the GNSS engine, the application version and the configuration parameters |
on | Will enable the GNSS module |
off | Will disable the GNSS module |
restart | Will power off/on the GNSS module |
position | Use this option to consult the current position |
cold-start | Will execute a cold start on the GNSS module |
warm-start | Will execute a warm start on the GNSS module |
hot-start | Will execute a hot start on the GNSS module |
antenna-on | Power on the GNSS antenna, 3.3 Volts are placed on the antenna connector |
antenna-off | Power off the GNSS antenna |
antenna-st | Antenna state (if it's connected or not) |
set-filter [options] | Use this option to configure the GNSS anti-drift filter, it receives as options the hdop, motion and speed(km/h). Valid ranges: 1.0 <= hdop <= 5.0; motion true/false; 0 <= speed < 100 |
set-rate | Use this option to change the GNSS nmea sentece output frequency. Valid options are 1, 5, and 10 Hz |
backlog create | Will create a GNSS backlog file, it receives as parameters the file name --name and the time window --time-win , the time window limit is 300 seconds |
backlog status | Returns the state of the GNSS backlog file specified with the --name argument |
set [options] | Use this option to enable or disable the simulation or nmea-log mode |
version | Returns the tool version |
help | Prints this help |
options | description |
---|---|
set-filter | [--hdop=<value>] [--motion=<value>] [--speed=<value>] |
set-rate | [--rate=<value>] |
backlog create | [--name=<value>] [--time-win=<value>] |
backlog status | [--name=<value>] |
set | [--simulation-mode=<true/false>] [--nmea-log=<true/false>] |
Examples:
# Get the gps state
$ apx-gps status
{"TIME":"2023-04-03T20:26:35Z","ENGINE":"xm1110","VERSION":"1.7.4","FIX":3,"LATEST_POINT":{"lat":25.783475,"lon":-80.293563,"alt":17.040,"speed":0.963,"heading":115.27,"epoch":1623959390},"filter":{"hdop":2,"motion":true,"speed":5},"rate":10,"antenna":"disconnected"}
# Where: TIME = GMT Timestamp in ISOFORMAT
# ENGINE = GPS chip
# VERSION = GPS version
# FIX = Fix quality, 1: 'Fix not available', 2: '2D', 3: '3D' (http://aprs.gids.nl/nmea/)
# LATEST_POINT
# lat = Latitude
# lon = Longitude
# alt = Altitude in meters above mean sea level
# speed = Speed in km/h
# heading = Heading in degrees from North, increasing eastwardly
# epoch = GPS epoch timestamp
# filter = anti-drift filter settings
# hdop = Min hdop
# motion = True if it needs to detect motion with accelerometer
# speed = Minimum speed
# rate = Rate of gps update (in Hz)
# antenna = Antenna status (disconnected, connected, or short-circuit)
# Perform a warm-start on the GPS module
$ apx-gps warm-start
# Change the GPS anti-drift filter to hdop of 1.8, movement detected, with speed of 50 km/h
$ apx-gps set-filter --hdop=1.8 --motion=true --speed=50
# Get the latest location
$ apx-gps position
"http://maps.google.com/maps?q=25.783560,-80.293480"
# Generate a backlog of the last 60 seconds, and next 20 seconds from now
$ apx-gps backlog create --name=mybacklog --time-win=-60,20
# Get the status of the gnss backlog
$ apx-gps backlog status --name=mybacklog
# Set Simulation mode
$ apx-gps set --simulation-mode=true
GNSS/GPS Simulator
apx-gps-sim
This tool lets you simulate tracking points in order to test geofences, speed limits, changes in heading, and anything related to the GPS.
# To view the help docs
apx-gps-sim help
# To start the simulator
apx-gps-sim start
Once the simulation has started you can use the following actions to control the application
action | description |
---|---|
status | Print the current status of the simulator. |
reset | Reset all values of current simulation. |
pause | Sets the speed to 0 |
move | Simulates motion for the device based on the speed and heading values |
set | Used to set the gps values |
stop | Stop the simulation |
help | Prints all the usages |
Once started it simulates the location of the device with the coordinates of the last known GPS.
Here's an example of a typical simulation. Each command goes one after the other.
# Start the simulator
apx-gps-sim start
# actions
set --speed=50
set --head=64
move
The above commands will start moving the device in a heading of 64° (North East) at 50 km/h. We can visualize the movement in the GPS section of the Management Tool or Pegasus.
To test events inside and outside of some geofence group use the following script, in this case we want to know if the vehicle entered into any geofence of the group "harrys_team" and to send an event if the vehicle entered with more than 10 kph.
# Define a tracking resolution
define tracking_resolution standard 30deg 20sec 500mts
# Generate an event when it meets any of the tracking resolution criteria
define event track group=tracking ack=seq label=trckpnt code=0 trigger=@tracking_resolution.standard.signal
# Signal for inside the geofence
define signal sg_geo_privet min_duration=1sec $geofences.harrys_team.inside
# Speed limit signals
define signal speed_zone_10 min_duration=1s $gnss.kph > 10
define signal speed_zone_15 min_duration=1s $gnss.kph > 15
define signal speed_zone_20 min_duration=1s $gnss.kph > 20
define signal speed_zone_50 min_duration=1s $gnss.kph > 50
define signal speed_zone_100 min_duration=1s $gnss.kph > 100
# Event for inside the geofence while speeding above 10km/h
define event speeding_10 group=tracking ack=seq label=speeding10 code=10 trigger=sg_geo_privet,speed_zone_10,and
Inputs/Outputs
apx-io
click here for legacy version of this tool
This tool allows management of the parameters associated with the inputs and outputs.
apx-io <action> <key> <value>
apx-io <action> <key>
apx-io <action>
action | description |
---|---|
set | Must be followed by key and value. Will set desired output for the device. |
get | Must be followed by key. Will obtain the value of the desired key |
getall | Must be followed by key. Will obtain all of the values for the desired key |
status | Prints virtual ignition status |
help | Prints all the usages |
Allowed values
set
key:
OUT1
,OUT2
,OUT3
,OUT4
, andvirtualign
value: for OUTX keys =
true
orfalse
or
--times
= integer between 1-10
--on
= from 20 to 1000 (milliseconds)
--off
= from 20 to 1000 (milliseconds)for virtualign key
--signal
=IN1
,IN2
,IN3
,IN4
,IN5
,IN6
,IN7
,PWR
,MOT
,AN1
,AN2
,DAN
--on_threshold
= from 0 to 28000 for ANx signals 0 or 1 for INx signals
--off_threshold
= from 0 to 28000 for ANx signals 0 or 1 for INx signals
--on_time
= from 0 to 60 (seconds)
--off_time
= from 0 to 60 (seconds)
get
key:
OUT1
,OUT2
,OUT3
,OUT4
,IGN
,IN1
,IN2
,IN3
,IN4
,IN5
,IN6
,IN7
,PWR
,MOT
,SO1
,SO2
,SO3
,SO4
,TIG
,AN1
,AN2
,DAN
,BAT
getall
key:
outputs
,inputs
,analogs
status
key:
virtualign
Examples:
# Activate output 2:
$ apx-io set OUT2 true
# Activate output 4, 3 times, ON for 1000ms and OFF for 1000ms
$ apx-io set OUT4 --times=3 --on=1000 --off=1000
# Get the value of all the analog inputs:
$ apx-io getall analogs
{"BAT":4.047,"DAN":11,"AN1":0,"AN2":0}
# Set virtual ignition with Analog Input 2
# Detects ON when the value is above 5000mV for 5 seconds, OFF when below 5000 for 5 seconds
$ apx-io set virtualign --signal=AN2 --on_threshold=5000 --off_threshold=5000 --on_time=5 --off_time=5
apx-io (legacy)
Tool that manages the device's general purpose inputs and outputs.
apx-io [action] [key] [value]
action | description |
---|---|
set | Must be followed by key and value. Will set desired output for the device. |
get | Must be followed by key. Will obtain the value of the desired key |
getall | Must be followed by key. Will obtain all of the values for the desired key |
help | Prints all the usages |
set
key:
OUT1
,OUT2
,OUT3
, andOUT4
value:
true
orfalse
get
key:
OUT1
,OUT2
,OUT3
,OUT4
,IGN
,IN1
,IN2
,IN3
,IN4
,IN5
,IN6
,IN7
,PWR
,MOT
,SO1
,SO2
,SO3
,SO4
,TIG
,AN1
,AN2
,DAN
,BAT
getall
key:
outputs
,inputs
,analogs
Examples:
# Get the value of all the analog inputs:
$ apx-io getall analogs
{"BAT":4.047,"DAN":11,"AN1":0,"AN2":0}
# Activate output 2:
$ apx-io set OUT2 true
Safe Immobilization
Tool that activates the device's safe immobilization feature. This feature activates the device's output 1 after certain conditions are met - thereby making it a safe activation.
Caution should always be exercised if using this to immobilize a vehicle.
apx-seco <command> [<options>]
Commands:
command | description |
---|---|
set [option] | Command to enable/disable the SECO mode and the SECO trigger |
status | It returns a json object with the current state of the SECO mechanism |
version | Returns the tool version |
help | Print this help |
Options:
option | description |
---|---|
-m, --mode | Valid values are enable and disable. When enabled, the user can not control the output 1 via 'apx-io set out1' command |
-t, --trigger | Valid values are enable and disable. When enabled, the SECO mechanism will try to activate the output 1 when safety conditions are met. Use disable to cancel the instruction or deactivate the output 1 |
Examples:
# enable the safe immobilization mechanism
$ apx-seco set --mode=enable
# activate output 1 safely
$ apx-seco set --trigger=enable
# check the status
$ apx-seco status
LTE-Modem
apx-mdm
Tool to manage the LTE module of the device. Allows you to configure the APN and other configuration related parameters as well as perform actions like sending an SMS, enabling airplane mode, or converting text to speech.
apx-mdm <command> [<args=value>]
COMMANDS:
command | description |
---|---|
status | Use this option to consult the current state and general information about modem network registration and configuration parameters. It returns a json object |
restart | Use this option for restarting the modem device. |
end-call | Use this option for ending an established voice call. |
version | Returns the tool version. |
COMMAND:
set [OPTIONS]
- Use this option to configure the parameters used by the modem application
option | description |
---|---|
-a, --apn | The access point name. Set to none to remove the value. |
-p, --pin | The SIM card PIN. Set to none to remove the value |
-u, --user | The username for the APN. Set to none to remove the value. |
-p, --pass | The password to access the APN. Set to none to remove the value. |
-b, --sim_sw_interval | The time interval in hours for changing from external SIM to embedded when no data connection is reached (default: 4) |
-c, --sim_priority | With this parameter, you can specify the sim card to use: e-sim embedded (default) or sim-card external |
-k, --keep_alive | The time interval in minutes to check the data connection. The default is 15 min , minimum: 1 min , and the maximum: 60,000 min . A value of 0 deactivates the keep-alive. |
-v, --call_validation | Use true for validating the phone number before answering the call, it depends on the authorized phone list added with phone_book option. By default, the device validates the phone number before answering the call |
-m, --sms_validation | Use 'true' for validating the phone number before processing the incoming sms, it depends on the authorized phone list added with phone_book option. By default, the device validates the phone number before processing the incoming sms |
-f, --airplane_mode | Use true for entering in airplane mode and false for returning to normal mode. |
COMMAND:
phone-book [SUBCOMMAND] [OPTIONS]
- Use this command to add, remove and consult the authorized phone book list
subcommand | description |
---|---|
add | Use this option to add a phone number to the authorized list. |
remove | Use this option to remove a phone number from the authorized list. |
list | Use this option to consult the phone number authorized list. |
option | description |
---|---|
-n, --number | The phone number to add or remove |
Disable the call identifier to answer calls from unregistered numbers
If you want Syrus to answer a call from a number not in the
phone_book
remember to first disable the call validation:# disable call validation $ apx-mdm set --call-validation=false # place a call to the Syrus sim's number and it'll pick up # remember you can use the apx-mdm end-call to end the call from the Syrus side
COMMAND:
send [OPTIONS]
- Use this command to send SMSs
options | description |
---|---|
-s, --sms | The message to be sent. |
-n, --number | The destination phone number |
COMMAND:
call [OPTIONS]
- Use this option for starting a voice call
options | description |
---|---|
-n, --number | The phone number to call |
COMMAND:
tts [OPTIONS]
- Text to speech. Use this option to turn text into sounding by using the Bluetooth speaker connected
options | description |
---|---|
-t, --text | The text to be reproduced |
Examples:
# Set the APN of the regular SIM card (not embedded)
$ apx-mdm set --apn="mycarrierapn.com" --user=myuser --pass=mypass
# Set the APN, remove the user and pass
$ apx-mdm set --apn=myapn.com --user=none --pass=none
# Set the priority of the SIM card used to the regular SIM (not embedded):
$ apx-mdm set --sim-priority=sim-card
# Add phone number to the phone book:
$ apx-mdm phone-book add -n=3013333333
# Send an SMS to 3013333333
$ apx-mdm send --n=3013333333 --sms='Testing Syrus4 SMS'
# Start a call with the number: 3013333333
$ apx-mdm call -number='+13013333333'
# Speak command
$ apx-mdm tts --text='Testing text to speech'
# Get the state of the LTE modem
$ apx-mdm state
{"manufacturer":"Quectel","revision":"EG25GGBR07A06M2G","model":"EG25","imei":"867698040023056","sim_imsi":"732123200007701","sim_state":"Not in Use","sim_type":"EMBEDDED","sim_id":"89883234500011949724","gsm_reg":1,"modem_state":"ON","gprs_reg":1,"rat":"FDD LTE","mcc_mnc":310260,"band":"LTE BAND 2","operator":"Wireless","esim_state":"READY","ip":"25.130.16.168","esim_imsi":"310260859157280","esim_id":"8901260852391572807F","rssi":15,"no_conn_time":0,"lac":8181,"cid":"24A8F0E","sim_sw_interval":8,"keep_alive":15,"sim_priority":"e-sim","apn":"super"}
apx-ppp
Manages the ppp connection to the internet with the specified profile.
apx-ppp [option] profile
option | description |
---|---|
start | Starts the pppd deamon with the profile specified |
stop | Stops the pppd process |
state | Returns 0 if daemon is running and ppp0 interface has an IP, 1 otherwise |
help | Prints this help message |
Example:
$ apx-ppp start default
Onewire
Manage devices that communicate via the 1-wire bus system like temperature probes and IButtons.
apx-onewire
Use this Apex tool to add/remove onewire devices to or from the whitelists found in /data/users/syrus4g/onewire/
. This tool also allows to get information about the onewire devices connected.
apx-onewire [type] [action]
apx-onewire [type] [action] [argument_1] [argument_2] ... [argument_n]
type |
---|
ibutton |
temperature |
action | description |
---|---|
add | Followed by argument_1 and argument_2 . Will add the alias found in argument_1 with the onewire id number found in argument_2 to the white list based on the valid type. Alias cannot be empty, must be of 50 characters or less, and cannot contain the character ':' . The onewire id must be exactly 16 characters long therefore you must place padding with leading zeros to complete the 16 digits. |
remove | Followed by argument_1 . The argument_1 can be either the alias or the onewire id which will be removed from the white list based on the valid type. |
remove_all | Not followed by any arguments. Will remove all of the onewire devices based on the type specified from the corresponding white list. |
remove_last | Not followed by any arguments. Will remove records of the last onewire device discovered. |
get | Followed by argument_1 . The argument_1 can be either the alias or the onewire id. Returns an object with information about the onewire device based on the type given. |
get_all | Not followed by any arguments, returns an array of objects for all the onewire devices based on the type specified. |
get_last | Not followed by any arguments, returns an object of the last onewire device that was connected based on the type specified. |
restart | Not followed by any arguments, not preceded by a type, will restart the onewire application. |
reset | Not followed by any arguments, not preceded by a type, will reset the onewire application. Deleting all white list files as well as previous information about past onewire devices. |
help | Not followed by any arguments, not preceded by a type, will print this message. |
version | Not followed by any arguments, not preceded by a type, will return the core and the tool version. |
status | Not followed by any arguments, not preceded by a type, will return the status of the onewire bus. 0 meaning operation is normal. -1 meaning that there is a fault in the onewire bus. |
Examples:
# add ibutton with alias: 'driver 1'
$ apx-onewire ibutton add 'driver 1' 0123456789123401
# read all ibuttons
$ apx-onewire ibutton get_all
{"ibuttons":[{"alias":"driver 1","id":"0012331241412401","whitelisted":true,"connected":false,"conn_epoch":null,"disc_epoch":null}]}
# add temperature alias for room1
$ apx-onewire temperature add room1 3501144D2797AA28
# read all temperatures
$ apx-onewire temperature get_all
{"temperatures":[{"alias":"room1","id":"3501144d2797aa28","value":null,"connected":false,"epoch":1619786506}]}
People Counting
apx-ndm-pc
Tool to manage the people counting camera.
apx-ndm-pc <command> [--<option>=<value>]
commands | description |
---|---|
start | starts the people counting. |
stop | stops the people counting. |
reset | reset the internal people counters. |
status | get actual counters status. |
report [OPTIONS] | returns the JSON formatted report. |
options | |
---|---|
report | [--from=<value>] [--to=<value>] |
The report is used to request a summary of the people counted
ALLOWED VALUES:
from
: epoch format -> 1668798420to
: epoch format -> 1668798420
Example
# Start
$ apx-ndm-pc start
# Stop
$ apx-ndm-pc stop
# Reset
$ apx-ndm-pc reset
# Status
$ apx-ndm-pc status
# Report
$ apx-ndm-pc report --from=1665316800 --to=1665331200
Power Save
apx-psm
Tool to manage the device's power save mode. The power save mode is ON by default where the device goes into a low power consumption mode after 5 minutes without the ignition wire detected. This behavior can be overwritten with this tool. Syrus 4 consumes ~200mA when using GNSS, modem and wifi, thus it's recommended to always have a power save mode configured, to avoid any issues with a car's battery for example.
Default PSM_STRING: IGN:0,SLP:300;IGN,MIN:720;300
apx-psm [action] [PSM_string]
action | description |
---|---|
immediate | This action is not followed by PSM_string, instead it orders the device to enter Power Save Mode with the previously loaded configuration. When a previous PSM doesn't exist the device will use the default PSM. |
mode | Must be followed by PSM_string and the only valid format is sleep_condition;wakeup_condition;wait_time . Signals for the conditions are separated by commas (, ) and conditions are separated by semicolons (; ). All of the sleep_condition signals must have a valid value of 0 or 1 and the colon (: ) character must be used to separate between signal and value. Note: MIN is the only signal for wakeup_condition that has a value. SLP signal cannot exist without a MIN signal and vice versa. Be sure to encapsulate PSM_string with "Quotation Marks" |
help | Prints this message. |
guide | Guides the user on how to properly create a Power Save Mode string. Note The device will be configured with the results of this guide. |
Configuration of the [PSM_string]
First enter the sleep_condition
. This is the condition the device must meet so that it will go into Power Save Mode. This condition is broken into signal:value
separated by commas where only the valid signals below are allowed and the only valid values are 0 (inactive) or 1 (active)
sleep_condition signals | description |
---|---|
IGN | Ignition state. |
IN1 | Input 1 state. |
IN2 | Input 2 state. |
IN3 | Input 3 state. |
IN4 | Input 4 state. |
IN5 | Input 5 state. |
IN6 | Input 6 state. |
IN7 | Input 7 state. |
PWR | External power state. |
MOT | Motion state. |
SO1 | Short-circuit on output 1. |
SO2 | Short-circuit on output 2. |
SO3 | Short-circuit on output 3. |
SO4 | Short-circuit on output 4. |
TIG | Ignition from main power supply state, this ignition is detected based on the signal frequency |
SLP | Time to wait for the device to go back into sleep mode in seconds (300 - 65535 seconds) |
Next enter the wakeup_condition
. This is the condition that lets the device know how it should return from the Power Save Mode. The device will wake up upon any of the given wake up signals being met. Only use the valid wake up condition signals described below. The only signal that uses a value is 'MIN' and this signal lets the device know how often to wake up. Example: MIN:10
will wake up every 10 minutes.
wakeup_condition signals | description |
---|---|
IN1 | Will wake up based any change detected in input 1. |
IN2 | Will wake up based any change detected in input 2. |
IN3 | Will wake up based any change detected in input 3. |
IN4 | Will wake up based any change detected in input 4. |
IN5 | Will wake up based any change detected in input 5. |
IN6 | Will wake up based any change detected in input 6. |
IN7 | Will wake up based any change detected in input 7. |
IGN | Will wake up upon ignition signal change. |
PWR | Will wake up upon external power source signal change. |
SO1 | Wake up due to a short in output 1. |
SO2 | Wake up due to a short in output 2. |
SO3 | Wake up due to a short in output 3. |
SO4 | Wake up due to a short in output 4. |
MOT | Will let the device wake up upon motion being detected. |
MIN | Lets the device know how often, in minutes, to wake up. 1 - 65536 (note this needs a value) |
Lastly, enter the wait_time
. This is the time the sleep condition must be met and sustained before the device will into Power Save Mode. This number is defined in seconds. The wait time must be between 300 seconds (5 minutes) or 65536 seconds (18 hours) inclusive.
About Power Saving Mode
Note that there is no way to remove the power save mode, however you can configure it in a way so that the device never falls asleep
Examples:
# Set the power save mode to go to sleep after 240 seconds (4min) (240) of no ignition detected (IGN:0), wake up for 5 minutes (SLP:300) every 10 minutes (MIN:10) or end the power save mode when motion is detected (MOT).
$ apx-psm mode "IGN:0,SLP:300;MOT,MIN:10;240"
# Set the power save mode to go to sleep after 300 seconds (300) of no movement detected (MOT:0), and wake up only when input1 is detected (IN1).
$ apx-psm mode "MOT:0;IN1;300"
# Set the power save mode to go to sleep after 5 minutes (300) of no movement or ignition (MOT:0,IGN:0), wake up every 2 hours (MIN:120) for 3 minutes (SLP:180) or end the power save mode when INPUT 1, or IGNITION, or MOTION is detected (IN1,IGN,MOT).
$ apx-psm mode "MOT:0,IGN:0,SLP:180;IN1,IGN,MOT,MIN:120;300"
Serial Interface
Manage the serial RS-232 interface of the device to communicate with accessories via the serial port.
apx-serial
Configures the RS-232 serial interface in different modes for communication with serial accessories such as Satcom & Sigfox communicator, fatigue sensor, mobile data terminal, rfid reader, or fuel level sensor.
apx-serial [option]
Fuel Level & RFID commands
Note that there are separate apx commands for fuel level sensor and rfid integration.
option | description |
---|---|
mode | Use this option to select the mode in which the user serial port will be used. By default the serial port is in console mode. If argument_1 is not found it returns the current mode. |
Selecting the mode
apx-serial mode MODE
MODE | description |
---|---|
console | Use console mode to send apx commands to interact with the device, for example, you can consult the state of the device inputs by sending apx-io getall inputs through a serial terminal at 115200 8 n 1. |
modem | Used when Satcom or Sigfox accessories are connected. |
fatigue_sensor | Used when communicating with a fatigue sensor accessory. |
fuel_sensor | Used for fuel sensor accessory |
mdt | Mobile data terminal mode for communication/data parsing of an external rs-232 accessory. |
Console
Send apx commands to the device and receive a response via the serial interface
Format:
apx-serial console APX_COMMAND
Modem
Used to communicate with other serial capable modem devices/accessories like the Syrus Satcom and Sigfox Communicator.
Format:
apx-serial modem [command]
command | description |
---|---|
state | Use this option to consult the current state of the serial modem device |
send | Use this option to send data through the serial modem device, max 340 characters with the serial-modem satcom. |
buffer_size | Followed by a number to configure the size of serial modem buffer. Range from 10 to 500. Default 100. If no argument provided it returns the current value. |
clear_buffer | Use this option to to clear the serial modem buffer. |
Fatigue Sensor
Used to communicate with a fatigue sensor. The photos captured by the fatigue sensor are automatically stored in: /data/users/syrus4g/fatigue_sensor
.
Format:
apx-serial fatigue_sensor [argument_1]
[argument_1] | description |
---|---|
state | Use this option to consult the current state of the sensor |
list | It returns the list of the photos stored in the device memory |
sensitivity | Use this option to consult/configure the sensor sensitivity. Range 2-11. Default 3. If no argument provided it returns the current value. |
min_speed | Use this option to consult/configure the warning start-up speed. Range 10-60. Default 10 km/h. If no argument provided it returns the current value. |
speeding | Use this option to consult/configure the sensor speed alarm rate. Range 50-150. Default 50 kph. If no argument provided it returns the current value. |
max_photos | Use this option to consult/configure the max number of photos that can be stored in the device memory. Range 10-100. Default 25. If no argument provided it returns the current value. |
speaker_volume | Use this option to consult/configure the sensor speaker volume. Range 0-2. Default 2. If no argument provided it returns the current value. |
auto_upload | Use this option to consult/configure the auto_upload mode, when enabled, the application will automatically upload the photos to the syrus4 server. 0: disabled, 1: enabled. Default disabled |
upload | Use this option to upload the photos to the syrus4 server |
capture_photo | Use this option to capture a photo |
delete_photos | Use this option to delete all the photos stored |
sensitivity | approximate delay time in seconds to alarm |
---|---|
2 | 2.2 seconds |
3 | 2.9 seconds |
4 | 3.7 seconds |
5 | 4.5 seconds |
6 | 5.3 seconds |
7 | 6.1 seconds |
8 | 6.9 seconds |
9 | 7.7 seconds |
10 | 8.5 seconds |
11 | 15 seconds |
speaker_volume | volume equivalent |
---|---|
0 | Speaker Off |
1 | Low |
2 | High |
Auto-upload
The auto-upload feature is used to automatically upload photos to DCT's server. In a future release we'll provide access to download the photos from DCT's server, if you're using Syruslang
Note that the photos captured by the fatigue sensor use the following format:
epoch-photo_description.jpeg
Where photo description can be any of the following:
- fatigue_alarm: driver fatigue detected
- fatigue_remind: driver fatigue reminder
- fatigue_warning: driver fatigue warning
- distraction: driver distracted
- no_portrait: driver not detected
- photo: regular photo captured with fatigue sensor
MDT mode
Places the device in an MDT mode, which allows you to receive and send data via the serial interface in a packaged format based on different criterias such as the size, time, and header among others.
Format:
apx-serial mdt [argument_1]
apx-serial mdt settings [baudrate] [type] [timeout] [max_size] [header] [tail] [mask] [offset]
[argument_1] | description |
---|---|
state | Returns a json with the current state and configuration parameters |
send | For sending data to the serial port |
settings | For setting up the mdt mode |
MDT Settings
[argument_n] | description |
---|---|
baudrate | The serial port baud rate. Valid values are 1200, 4800, 9600, 19200, 38400, 57600 and 115200 |
type | For this version only x is supported (hexadecimal mode) |
timeout | It is the time that the application waits before sending the packed data when at least one byte has been received. Range 0-900s. Use 0 to ignore this setting |
max_size | When this limit is reached the application sends the packed data. Range 0-1024. Use 0 for ignoring this setting |
header | The protocol head, up to 4 bytes, for example 0x0b0c . Up to 4 hexadecimal bytes. Use 0 for ignoring this setting |
tail | The protocol tail, up to 4 bytes, for example 0x0d0a . Up to 4 hexadecimal bytes. Use 0 for ignoring this setting |
mask | The mask used, up to 4 bytes. Use the mask for filtering the data, depending on it, the application only packages the data if the corresponding byte array changes. The mask is only applied if the header and offset are configured. Use 0 for ignoring this setting. |
offset | The number of bytes after the last byte of the header for applying the mask configured. Range 0-1024. Use 0 for ignoring this setting |
Note that if only the tail
is configured, the application will package the data every time the tail is received.
For scenarios walking you through some sample MDT configurations refer to the connect section.
Examples:
# Enable the console mode
$ apx-serial mode console
# Send an apx command
$ apx-serial console apx-gps position
# Configure the serial port in modem mode
$ apx-serial mode modem
# Configure the serial port in modem mode, which is used when Satcom or Sigfox accessories are connected, in the example below, 50 is an optional parameter for configuring the size of the buffer for the serial modem.
# The range of the buffer is from 10 to 500. Default is 100.
$ apx-serial modem buffer_size 50
# Consult the current state of the serial modem device.
$ apx-serial modem state
{"state":"connected","type":"satcom","id":"300234062206840","signal":3,"version":15,"buff_size":50,"buff_count":1}
# To send a message
$ apx-serial modem send ">REV331852148....;ID=35...<"
# Note that it returns an error if the modem mode is not active. and if the message length is greater than 340 characters
# To change the sensitivity so it's more sensitive
$ apx-serial fatigue_sensor sensitivity 2
# To change the minimum speed used to trigger warnings to 25kph
$ apx-serial fatigue_sensor min_speed 25
# To check the state of the fatigue sensor
$ apx-serial fatigue_sensor state
{"state":"connected","sensitivity":3,"speaker_volume":2,"min_speed":10,"speeding":50,"max_photos":10,"nbr_photos":10,"latest_photo":"1616001062-photo.jpeg"}
# To list photos captured by fatigue sensor
$ apx-serial fatigue_sensor list
["1615580038-distraction.jpeg","1615580071-fatigue_alarm.jpeg","1615580119-distraction.jpeg","1615580207-fatigue_alarm.jpeg","1615580231-distraction.jpeg","1615580295-photo.jpeg","1615580324-photo.jpeg","1615580361-distraction.jpeg","1615997099-photo.jpeg","1616001062-photo.jpeg"]
# For setting the serial mode to mdt
$ apx-serial mode mdt
# To set the mdt mode with
# baudrate of 115200, in HEX mode, a timeout of 10 seconds,
# max size of 20 bytes, a header of 0x0A, tail of 0x0B,
# a mask of 0x01, and an offset of 5
$ apx-serial mdt settings 115200 x 10 20 0a 0b 01 5
# For getting the state of the serial mode
$ apx-serial mode mdt state
{"mode":"enabled","baudrate":115200,"type":"x","timeout":10,"max_size":20,"header":"0a","tail":"0b","mask":"01","offset":5}
# To send a message with '3132330D0A' to the serial port
$ apx-serial mdt send '3132330d0a'
# For enabling the fuel sensor over the serial RS-232
$ apx-serial mode fuel_sensor
# Set the consumption and fuelling thresholds
$ apx-serial-fs set --fuelling-threshold=250 --consumption-threshold=70 --consumption-window=20
Using MDT messages with special characters
Note that if you are using MDT mode to send messages via the Serial Port to the Syrus you may have to escape special characters
# query the cellular network connection status of the syrusjs application $ syrus-apps-manager send-message __cloud_syrusjs "get value \$net_cell.connected"
apx-serial-fs
Fuel sensor mode for the serial port.
$ apx-serial-fs <command> [<options=value>]
command | description |
---|---|
set [OPTIONS] | Use this command to configure the fueling threshold, consumption threshold, and consumption window |
status | Use this command to consult the current sensor state |
version | Returns the tool version |
help | Print help message |
OPTIONS
option | description |
---|---|
-f , --fuelling-threshold | The threshold used for triggering the fueling signal. |
-c , --consumption-threshold | The threshold used for triggering the consumption signal. |
-w , --consumption-window | The time window in seconds used for evaluating the consumption behavior. |
Examples
# Set the consumption threshold to 100 in 20seconds
$ apx-serial-fs set --consumption-threshold=100 --consumption-window=20
# Get the status of the fuel sensor
$ apx-serial-fs status
apx-serial-rfid
RFID connected to serial port.
$ apx-serial-rfid <command> [<options=value>]
command | description |
---|---|
set [OPTIONS] | Use this command to add an ID to the authorized list. It can also be used for changing the alias of an existing ID. |
remove [OPTIONS] | Use this command to remove an ID from the authorized list. Use --all for removing the complete list. |
list | Use this command to list the authorized list. |
get [OPTIONS] | Use --last to get the last ID read. |
clear [OPTIONS] | Use --last to clear the information about the last ID read. |
version | Returns the tool version. |
help | Print this help. |
options | description |
---|---|
-i , --id | The ID to be added or removed. |
-a , --alias | The alias to be associated with an ID. |
--all | To be used with the remove command. |
--last | To be used with the get/clear commands. |
Examples
# Set rfid 1234 to driver1
apx-serial-rfid set --id=1234 --alias=driver1
# Remove rfid 1234
apx-serial-rfid remove --id=1234
# Remove all rfid values
apx-serial-rfid remove --all
# Get last rfid value
apx-serial-rfid get --last
apx-serial-slctr
Manages the input serial interface of the device. You can only select between one of RS-232, J1708, or RS485.
apx-serial-slctr [option]
option | description |
---|---|
0 | RS232. It is the default option |
1 | J1708 bus |
2 | RS485 |
help | Prints this help message |
Example:
# Send the following command to enable the J1708 bus as the input serial interface.
$ apx-serial-slctr 1
System
apx-about
Information about the system and it's resources.
$ apx-about
{"ram":{"total":506084,"used":107824,"free":229732,"available":404616},"cpu":{"currF":1000,"usage":19.1926,"governor":"ondemand","stats":{"300":1319.28,"600":16152.25,"720":132.79,"800":52.43,"1000":299.93}},"rootfs":{"total":444018,"free":187666},"datafs":{"total":2255680,"free":2078392},"uptime":17958,"loadAvg":[1.83,1.71,1.65],"apexVersion":"apex-20.22-rc.8","releaseDate":"20200604000110","kernelVersion":"5.4.20-g738552d0b0","hostname":"syrusrouter"}
apx-core
Apex package manager for installing and removing software packages.
apx-core [option]
option | description |
---|---|
list | List the Apex Core packages installed |
update | Downloads the package list from the DCT repository. It gets the list of the newest packages with its dependencies and returns the list of the DCT packages available for updating |
recover | Allows to recover from broken packages when installing doesn't finish correctly |
install | Install one or several packages at a time by providing their names |
remove | Removes a software package from apex system |
reinstall | Removes the software package and reinstall it |
add_dev_repo | Adds the DCT developer repository to the package manager. It enables some linux packages to be installed. To get the list of the available packages, please consult https://apex.digitalcomtech.com/dev-packages.txt |
rm_dev_repo | Removes the DCT developer repository |
version | Returns the tool version. |
help | Prints the help message |
Example:
# list dct-apex packages installed
$ apx-core list
# install latest versions of syrus-gps and syrus-ecu packages
$ apx-core install syrus-gps syrus-ecu
# install specific version of syrus-gps
$ apx-core install syrus-gps=1.0-r0.1
apx-eeprom
Use this tool to primarily manage data inside the EEPROM (electrically erasable programmable read-only memory).
apx-eeprom [<command>] [--arguments]
command | description |
---|---|
read | Takes one argument --key and it returns the key value pair if it exists. |
write | Takes two arguments --key and --value . Will write the key value pair to the EEPROM. Since the EEPROM is of 32768 bytes, the keys are limited to 12 characters, and the value is limited to 50 characters. This command will OVERWRITE a key if it already exists. Only valid ASCII characters are allowed. |
remove | Takes one argument --key and it removes the key defined if it exists. |
list_all | Takes no arguments and it prints all of the valid key value pairs found inside the eeprom. |
[--arguments] | description |
---|---|
read | [--key] |
write | [--key] [--value] |
remove | [--key] |
Examples:
# write keys imei & foo with values into EEPROM
$ sudo apx-eeprom write --key=imei --value=867698040023056
$ sudo apx-eeprom write --key=foo --value=bar
# read key called imei from EEPROM
$ sudo apx-eeprom read --key=imei
{"key":"imei","value":"867698040023056"}
# list all key value pairs in eeprom
$ sudo apx-eeprom list_all
{"pairs":[{"key":"imei","value":"867698040023056"},{"key":"foo","value":"bar"}]}
apx-ext-memory
Tool that prepares an external storage device such as an SD card to be compatible with Apex OS.
apx-ext-memory <command> [<args=value>]
[command] | description |
---|---|
format [OPTIONS] | Prepares the external device in order it can be used by the operating system. Warning!, this process will erase all the data stored in this device. |
status [OPTIONS] | Returns a json object with general information about the state of the external memory selected with --type |
help | Prints this help |
[OPTIONS] | description |
---|---|
-t , --type | The type of external memory conneced (sd or usb ) |
-y | Use this option to force the format without asking for confirmation |
-c | Use this option to force the format when the memory is being used. This will cause the device to be restarted. |
Examples:
$ apx-ext-memory format --type=sd
$ apx-ext-memory status --type=sd
apx-leds
Tool that manages the device's LEDs.
$ apx-leds <command> <args=value>
COMMANDS | DESCRIPTION |
---|---|
set [OPTIONS] | Use this command to change the system LED behavior |
version | Returns this tool version. |
help | Print this help |
OPTIONS | DESCRIPTION |
---|---|
-c, --color | Valid colors are red, green, yellow, and blue. |
-m, --mode | Valid modes are: |
on | (Deprecated) |
off | Color led fully off. This option is not valid for red led |
heartbeat | Color led simulates a heart beat thump-thump-pause |
one_short | 100ms on - 900ms off |
two_short | 100ms on - 100ms off - 100ms on - 700ms off |
one_long | 300ms on - 700ms off |
two_long | 300ms on - 300ms off - 300ms on - 100ms off |
low_freq | 500ms on - 500ms off |
flash | 10ms on - 990ms off |
LED Modes
Note that the LED mode is executed in sequential order, so the next activation of the mode happens after all other LEDs have been executed.
LEDs meaning
Red:
- Heartbeat: APEX Running
- Short blinking: Power saving mode
Green:
- Long Blink: Searching for GSM
- One Blink: Registered in GSM
- Two blinks: Connected with active data session
Orange:
- Long Blink: Searching for GPS
- One Blink: GPS low quality
- Two blinks: GPS good quality
Examples:
$ apx-leds set --color=blue --mode=low_freq
apx-logger
Tool for communicating with the SyrusCloud remote diagnostic application.
apx-logger [level] [message]
[level] | description |
---|---|
**crit** | Critical level message |
**error** | Error level message |
**warn** | Warning level message |
**info** | Info level message |
- crit, error, warn - types are sent to the syrus-cloud as soon as network connection be ready
- info - these messages are queued into the syrus-cloud's buffer and when a new connection is established they are transmitted
[message] | description |
---|---|
message | The message that is going to be sent to the syrus-cloud, enclosed in "quotes" |
Examples:
$ apx-logger info "This is an information message for the cloud, it will be queued"
$ apx-logger crit "This is a critical message for the cloud, it will be sent immediately"
apx-logrotate
This tool lets you read and configure the log rotation mechanism.
apx-logrotate <command> [<args=value>]
command | description |
---|---|
status | Reads the current log rotation configuration. |
configure | Configure a new or modify a current log rotation. |
remove | Remove a log configuration. |
force | Force log rotation for a specific log configuration. |
version | Returns the tool version. |
help | Print this help. |
options | description |
---|---|
-n, --name | To select log rotation configuration, (--name=all) to select all at reading. |
-p, --path | The location of the file we want to rotate(--path=/route/to/file.log). |
-s, --size | The minumum size of the file before compression and rotation (--size=200M) . |
-r, --rotate | The total number of compressed files to keep in memory (--rotate=5). |
-c, --compress | Indicate if files most be compressed (--compress=true). |
-f, --force | To force the rotation based on the current configuration. |
Examples:
# To get all the log configurations:
$ apx-logrotate status --name=all
# To create or modify a log rotation configuration:
$ apx-logrotate configure --name=syrus_instance --path=/data/logs/syrus_instance-out.log
# To remove a log configuration:
$ apx-logrotate remove --name=syrus_instance
# To force rotation for testing:
$ apx-logrotate force --name=syrus_instance
apx-os-update
Tool that updates the device's operating system. Careful when forcing the update of the OS over the air as it can consume a lot of data.
apx-os-update [option]
option | description |
---|---|
check | Check if an update is available in the dctserver |
start | Start the update by using the dctserver or by specifying the location |
-f , --force | The same as start but without checking the network interface |
-p , --path | Specify the path of the apex OS file |
state | Return the state of the current update process |
help | Prints the help message |
Examples:
# Check if there's an update available or if there's one already in progress
$ apx-os-update check
{"mess":"Update available"}
# or
{"mess":"Update in progress. This will take a few minutes"}
# Start an upgrade to the latest stable version (must be connected via wifi, otherwise use -f flag)
$ apx-os-update start
# Update from an SD card mounted on the device
$ apx-os-update start -f -p /media/mmcblk0p1/apex-22.44.2
apx-system
Tool to check general system information of the device, and reboot/restart it.
apx-system [option]
option | description |
---|---|
about | It returns a json object with general information about the system |
reboot | Use this option for rebooting/restarting the apex OS |
full_state | It returns the full state of the system depending on the epoch received |
set_name | Use this option for changing the system name, it is highly recommended to use a name that starts with syrus . Remember that the user session needs to be restarted in order for the change to be applied |
restart | Use this option for restarting syrus running services. |
set_data_files | Use this option to set syrus4g as the owner of /data applications and configuration files |
help | Prints the help message |
Examples:
# Will return a json object with all the information available
$ apx-system full_state 0
{"system":{"apex":{"version":"20.35-rc.1","date":"20200911213938","kernel":"5.4.20-g738552d0b0","epoch":1601657925},"ram":{"total":506084,"epoch":1601657925},"dataFs":{"total":2255680,"epoch":1601657925},"rootFs":{"total":444018,"epoch":1601657925},"uptime":{"since":"2020-10-02_14:59:58","epoch":1601657925},"epoch":1601657925},"gps":{"engine":{"name":"","epoch":1601657925},"filter":{"hdop":,"motion":,"speed":,"epoch":1601657925},"epoch":1601657925},"mobile":{"sim":{"type":"e-sim","swInterval":8,"epoch":1601657925},"gnss":{"state":"","epoch":1601657925},"rf":{"apn":"","keepAlive":15,"epoch":1601657925},"nbrAuth":{"call":,"sms":,"epoch":1601657925},"epoch":1601657925},"core":{"apex":{"bist":"0.0.12-r0.0","rules":"1.0.0-r0","start":"1.0.3-r0.1","tools":"1.0.9-r0.0","uchip":"1.0.3-r0.2","epoch":1601657925},"syrus":{"api":"1.5.2-r0.1","bt":"0.0.5-r0.0","bt-tools":"1.0.0-r0","counters":"1.0.3-r0.1","ecu":"1.0.1-r0.1","geofences":"0.0.5-r0.0","gps":"1.1.1-r0.0","imu":"1.0.9-r0.0","interface":"1.0.3-r0.0","mdm":"1.1.1-r0.3","ui":"0.10.1-r0.0","watcher":"0.0.3-r0.1","epoch":1601657925},"epoch":1601657925},"epoch":1601657925}
# Will return a json object with information that has a timestamp newer than the reference
$ apx-system full_state 1599573699
# Restart the gps module
$ apx-system restart syrus-gps
apx-user
apx-user [option] [argument_1] [argument_2] [argument_3]
option | description |
---|---|
checkuser | It returns "Valid User" if the user's password validation is successful, receives username as [argument_1] and password as [argument_2] |
changepass | It returns "Password Updated" if password has been successfully changed, receives username as [argument_1] , the current password as [argument_2] , and the new password as [argument_3] |
help | Prints the help message |
Note that passwords must be between 6 to 63 characters long
Examples:
$ apx-user changepass syrus4g 123456 mynewpass
apx-watcher
Used to manage the keep-alive messages with syrus cloud remote management interface.
USAGE:
$ apx-watcher <command> [<args=value>]
commands | description |
---|---|
set [OPTIONS] | Set the connection time and always on flag |
help | Print this help |
status | Returns a json object with general information about the state of the syrus-watcher application |
options | description |
---|---|
-c, --conn_time | Time in minutes used for sending the keep alive message to the syrus cloud. The default value is 480 minutes = 8 hours. Use 0 for disabling the syrus-watcher task, if this task is disabled the device will not connect with the syrus-cloud |
-a, --always_on | The flag used to control the connection with syrus-cloud. 0: Disabled, 1: Enabled (Default) |
Example:
# To change the keep-alive message with Syrus Cloud (https://cloud.digitalcomtech.com) to every 10 minutes and disable always_on
$ apx-watcher set --conn_time=10 --always_on=0
# to check the status of apx-watcher
$ apx-watcher status
{"conn_time":10,"always_on":0}
Tracking
apx-tracking
Tool that's used to manage tracking criterias' on the device. The tracking notification will trigger whenever any one of the criteria is met. Heading and distance notifications depend on valid GPS.
Create or edit a tracking criteria
apx-tracking <command> [<options>]
Commands:
commands | description |
---|---|
set [options] | Command to add or edit the tracking criteria |
get namespace | Command to consult a tracking criteria |
getall | It returns a list with all the tracking criteria configured |
delete namespace | Command to delete the tracking criteria |
version | Returns the tool version |
help | Print this help |
Options:
options | description |
---|---|
-n --namespace | The name used as a reference to identify the tracking criteria. Max 60 characters. |
-h --heading | The heading delta threshold for triggering notifications based on heading changes. Use 0 to disable. Range (0-180) |
-t --time | The time limit in seconds for triggering tracking notifications. Use 0 to disable. Range (0-86400) |
-d --distance | The distance threshold in meters for triggering tracking notifications based on the traveled distance. Use 0 to disable. Range (0-100000) |
-p --pacc | This is optional and can be used to set a positive acceleration threshold in kph/s |
-o --nacc | This is optional and can be used to set a negative acceleration threshold in -kph/s |
Examples:
# To set a tracking criteria for triggering notifications every 45 deg, 5 min or 100 meters
$ apx-tracking set --namespace=test --heading=45 --time=300 --distance=100
# To set a tracking criteria for triggering notifications every 20°, or 120 seconds, or +10 kph/s, or -8 kph/s
$ apx-tracking set --namespace=test --heading=20 --time=120 --pacc=10 --nacc=-8
# Return test tracking criterias configured
$ apx-tracking get test
# Delete test tracking criteria
$ apx-tracking delete test
Time Windows
This tool allows you to read and configure time windows, which trigger can be used programatically with Syruslang to trigger actions and events based on a specific time of day.
apx-time-window <command> [<args=value>]
Commands:
commands | description |
---|---|
status [options] | Reads a current time window state and configuration. |
set [options] | Configure or modify a time window. |
remove [options] | Remove a time window configuration. |
version | Returns the tool version. |
help | Print this help. |
Options:
options | description |
---|---|
-n , --name | The name of the desired window. |
-f , --from | Time window start time. Format hh:mm:ss |
-t , --to | Time window end time. Format hh:mm:ss |
-d , --days | Active days of the week denoted by an array of 0 or 1 from Sunday to Saturday (1,1,1,1,1,1,1) |
-s , --start | The starting day for the time window (01/01/2022) |
-f , --end | The ending day for the time window (31/12/2022) |
Examples:
# To get all the windows configurations:
$ apx-time-window status --name=all
# To create or modify a window configuration:
$ apx-time-window set --name=syrus_instance --from=13:00:00 --to=14:00:00
$ apx-time-window set --name=syrus_instance --from=13:00:00 --to=14:00:00 --days=0,1,1,1,1,1,0
$ apx-time-window set --name=syrus_instance --from=13:00:00 --to=20:00:00 --start=01/01/2022 --end=31/12/2022 --days=0,1,1,1,1,1,0
# To remove a window configuration:
$ apx-time-window remove --name=syrus_instance
Video
This tool configures the actions to be carried out in the processing of video files.
apx-video
apx-video <command> [<args=value>]
description | |
---|---|
set [OPTIONS] | Set the general configuration. (destination, reserved space, audio, mac, and id) |
get [OPTIONS] | Get the general configuration. (mac and version) |
remove [OPTIONS] | Remove unused files and/or a camera from the configuration file. |
add_camera [OPTIONS] | Add a new camera to the configuration file. |
record [OPTIONS] | Start or stop the video recording for a specified camera/cameras stored in the configuration file. |
stream [OPTIONS] | Start or stop the video streaming for a specified camera/cameras stored in the configuration file. |
create_clip [OPTIONS] | Find the video files from history location in a specified time window for one camera or all. Cameras stored in the configuration file and creates a video clip. |
create_snapshot [OPTIONS] | Use the incoming data from RTSP or a clip file to take a snapshot for the cameras stored in the config file. |
update_list [OPTIONS] | Shows the event clips information merge with (timeline or history tree) as json |
clip_status [OPTIONS] | Returns the state of the last 25 clips processed. |
snapshot_status [OPTIONS] | Returns the state of the stored snapshot or the state of one selected. |
cipia_config [OPTIONS] | Modify the configuration files of Cipia |
timeline [OPTIONS] | Get history timeline information per camera in a max range of one day (24 hours). |
restart [OPTIONS] | Restart the core application of the chosen module. |
status | Shows the status of the cameras stored in the config file, the values associated with the memory space are given in MB. |
version | Shows the actual version of the apx-video tool. |
always_recording [OPTIONS] | Set always run video record at the start of the application. |
[OPTIONS] | |
---|---|
set | [--destination=<value>] [--reserved_percentage=<value>] [--camera=<value>] [--audio=<value>] [--mac=<value>] [--id=<value>] [--device=<value>] |
get | [--device=<value>] [--mac=<value>] [--version=<value>] |
add_camera | [--type=<value>] [--camera_name=<value>] [--ip=<value>] [--port=<value>] [--user=<value>] [--pass=<value>] [--resolution=<value>] [--audio=<value>] [--uri=<value>] |
remove | [--type=<value>] [--camera=<value>] [--delete_files] |
record | [--status=<value>] [--camera=<value>] |
stream | [--status=<value>] [--camera=<value>] [--host=<value>] [--video_port=<value>] [--audio_port=<value>] [--timeout=<value>] |
create_clip | [--name=<value>] [--camera=<value>] [--time_win=<value>] [--from=<value>] [--to=<value>] |
create_snapshot | [--name=<value>] [--camera=<value>] [--clip=<value>] |
clip_status | [--camera=<value>] [--name=<value>] |
snapshot_status | [--name=<value>] |
always_recording | [--status=<value>] |
update_list | [--since=<value>] [--from=<value>] [--to=<value>] [--include_history] |
timeline | [--from=<value>] [--to=<value>] [--camera=<value>] |
restart | [--module=<value>] |
status |
FORMATS | description |
---|---|
[destination] | Micro-sd card -> sd , USB device -> usb , Internal memory -> internal |
[reserved_percentage] | Reserved space in memory defined in megabytes. e.g --reserved_percentage=5000 (5000 Mb or 5Gb) |
[type] | Type of camera you work with. IP ONVIF camera -> onvif , Dashcam -> dashcam , Movon MDSM-7 Camera -> mdsm7 |
[resolution] | Preferred resolution in the output videos. 1080p -> FHD , 720p -> HD , 480p -> SD . Default resolution HD -> 720p. |
[audio] | Set to true to record audio (must be enabled on the camera). --audio=true or false |
[time_win] | Time before and after to create a video clip, -time_backward,+time_forward in seconds. e.g --time_win=-60,+30 . -60sec = 60 seconds before, +30sec = 30 seconds after. (Max ranges: time_backward = 60sec, time_forward=30sec) |
[always_recording] | Set to true to enable always ON video recording at the start of the application. --status=true or false . Default true . |
[from] [to] | Epoch timestamp to retrieve video from timeline ranges. Max range between --from and --to is 24 hours |
[module] | Network device manager ndm or video |
[timeout] | Duration in seconds of the streaming. e.g --timeout=120 |
[codec] | Video codec h264 or h265 |
Always recording
The
always_recording
flag istrue
by default. To disable it you need to set the--status=false
status | description |
---|---|
0 | STARTING |
1 | RUNNING |
2 | FINISHED_BY_EOS |
3 | NOT_RUNNING |
4 | FINISHED_BY_ERROR |
Example:
# GENERAL CONFIGURATION
# Set the destination of video recording to an SD card mounted on the Syrus4 with a max % of 100
$ sudo apx-video set --destination=sd --reserved_percentage=100
# Disable the audio of the camera called: driver cam
$ apx-video set --camera=driver_cam --audio=false
# Set the Cipia MAC address & ID
$ apx-video set --device=cipia_fs10 --mac=A4:04:50:3C:BD:7C --id=E321290376
# GET GENERAL CONFIGURATION
# Get Cipia MAC address
$ apx-video get --device=cipia_fs10 --mac
# Get Cipia FW version
$ apx-video get --device=cipia_fs10 --version
# ADD CAMERAS
# Add an ONVIF IP camera
$ sudo apx-video add_camera --type=onvif --camera_name=cam_1 --ip=192.168.0.52 --user=admin --pass=admin --resolution=FHD --audio=true
# Add a Movon MDSM-7 fatigue sensor camera
$ sudo apx-video add_camera --type=mdsm7 --ip=192.168.0.52 --port=6564
# Add a Cipia fatigue sensor camera
$ sudo apx-video add_camera --type=cipia --host_address=127.0.0.1
# Add a Dashcam
$ sudo apx-video add_camera --type=dashcam --camera_name=dashcam_1 --ip=192.168.0.52 --user=admin --pass=admin --resolution=FHD --audio=true
# Add a Dashcam with live stream
$ sudo apx-video add_camera --type=dashcam --camera_name=dashcam_2 --uri=rtsp://USERNAME:[email protected]/ch1/sub/video
# REMOVE CAMERAS
# Remove back camera from configuration and delete video files
$ sudo apx-video rm_camera --camera=back_cam --delete_files
# Remove Movon MDSM-7 fatigue camera (keeps files)
$ sudo apx-video rm_camera --type=mdsm7
# START/STOP RECORDING
# Start recording on all cameras
$ sudo apx-video record --status=start
# Stop recording for a particular camera
$ sudo apx-video record --status=stop --camera=front_cam
# CREATE VIDEO CLIPS
# Create a video clip on all cameras called '1632141204_crash' for the last 60 seconds and next 30 seconds
$ sudo apx-video create_clip --name=1632141204_crash --time_win=-60,+30
# Create a video clip called '1632141204_crash' for the last 60 seconds
$ sudo apx-video create_clip --name=1632141204_crash --camera=back_cam --time_win=-60
# Create a video clip from all cameras with a from and to date (see timeline to view the available video ranges)
$ sudo apx-video create_clip --name=1632141204-crash --from=1632111204 --to=1632121204
# CLIP STATUS
# View the clip status for camera 'front_cam'
$ sudo apx-video clip_status --camera=front_cam
# View the clip status for a particular video clip
$ sudo apx-video clip_status --name=1632141204-crash
# VIDEO STREAMING
$ sudo apx-video stream --status=start --camera=cam_1 --host=videos.pegasusgateway.com --video_port=5006 --audio_port=5007 --timeout=120 --stream_id=817919789179
$ sudo apx-video stream --status=stop
# ALWAYS RECORDING
# Set always recording to true
$ sudo apx-video always_recording --status=true
# GET TIMELINE
# Get a timeline of the available videos to retrieve a video clip from
$ sudo apx-video timeline --from=1632141204 --to=1632142204
# Get a timeline for a particular camera
$ sudo apx-video timeline --from=1632141204 --to=1632142204 --camera=my_cam
[
{
"type": "onvif",
"name": "front_door",
"range": [
"1633090417",
"1633715624"
],
"ranges": [
[
"1633501423",
"1633501499"
]
]
},
{
"type": "onvif",
"name": "rear_door",
"range": [
"1632753622",
"1633715624"
],
"ranges": []
}
]
# UPDATE VIDEO LIST
# Update video list since a particular time
$ sudo apx-video update_list --since=164894646
# Update video list from a time range and include history
$ sudo apx-video update_list --include_history --from=164894646 --to=1648978486
# RESTART
# Restart the net device manager module (handles driver fatigue camera mdsm-7 for example)
$ sudo apx-video restart --module=ndm
# Restart the video module
$ sudo apx-video restart --module=video
# STATUS
# Status of the cameras
$ sudo apx-video status
{
destination: "sd",
reserved_space: 97540,
n_cams: 2,
cameras:[
{
name: "CAM1",
state: 3
},
{
name: "CAM2",
state: 3
}
]
}
# Modify Cipia config file, note that the settings are set with a flattened key and value inside a json object
# it's recommended to send this as a script via Syrus Cloud
$ sudo apx-video cipia_config --object='{"WifiSettings.SSID":"hotspotlab","WifiSettings.Password":"123456","EventsSettings.DriverDistracted.ReportImage":false}'
# Change video codec to h265 when configuring the camera
$ sudo apx-video add_camera --type=onvif --camera_name=cam_1 --ip=192.168.0.52 --user=admin --pass=admin --codec=H265 --audio=true
# VERSION
# Get video tool version
$ sudo apx-video version
Cipia
apx-ndm-cipia
Tool to manage the Cipia FS10 device.
Version: 0.0.1
NAME:
apx-ndm-cipia -- This tool controls the actions of the NDM application in its cipia sub-module.
USAGE:
apx-ndm-cipia <command> [--<option>=<value>]
COMMANDS:
configure - configures the cipia device based on config files.
status - returns the Cipia current status.
set - stores Cipia MAC and ID or modify a setting in the config file.
get - get Cipia version or MAC and ID stored.
remove - remove stored MAC and ID.
update - request the Cipia update
Arguments:
[--mac=<value>] [--id=<value>]
ALLOWED VALUES:
mac: A4:04:50:3C:BD:7C or a404503cbc7c
EXAMPLES:
Configure:
apx-ndm-cipia configure
Set:
# set MAC and Cipia ID
apx-ndm-cipia set --mac=a404503cbd7c --id=E321290376
# update parameters from the configuration file
apx-ndm-cipia set --parameter='{"WifiSettings.SSID":"hotspotlab","WifiSettings.Password":"123456","EventsSettings.DriverDistracted.ReportImage":false}'
# save the changes with configure command
apx-ndm-cipia configure
Get:
apx-ndm-cipia get --mac
apx-ndm-cipia get --id
apx-ndm-cipia get --firmware_version
apx-ndm-cipia get --core_version
apx-ndm-cipia get --tool_version
Status:
apx-ndm-cipia status
Remove:
apx-ndm-cipia remove --mac
Update:
apx-ndm-cipia update
WiFi
apx-wl-pwr
Tool to manage the wifi bluetooth module. Turning it off can help conserve power.
sudo apx-wl-pwr [action]
action | description |
---|---|
on | Power on the wl1835 MOD |
off | Power off the wl1835 MOD. WL1835 is a non-removable device, so it cannot be turned off. This option was preserved for compatibility issues |
Example:
# Power on wifi/bluetooth module
$ sudo apx-wl-pwr on
apx-hotspot
Manages the hotspot functionality on the device. Allows you to configure the SSID and password when enabling the hotspot. The password is protected with WPA2-PSK security.
sudo apx-hotspot [action]
sudo apx-hotspot [option] [value]
action | description |
---|---|
start | It starts the udhcpd and hostapd services used by hotspot app |
stop | It stops the hotspot services |
reset | It executes a stop-start in the same call |
list | It returns the list of the connected clients to the hotspot |
state | Returns status: Enabled/Disabled and other info |
help | Prints this help message |
option | description |
---|---|
route | Use this option for forwarding the wlan traffic to another interface, it allows you to have internet access by specifying the output interface, available values: ppp0 , eth0 |
ssid | Use this option for changing the network identifier |
pass | Use this option for changing the hotspot password (minimum of 8 characters) |
country | Use this option for changing the country_code (2-letter ISO Code) |
IP address ranges
Note that the range of IP addresses that the hotspot assigns is from:
192.168.9.100 to 192.168.9.254
.If you require working with static IP addresses you can use from
192.168.9.2 to 192.168.9.99
Example:
# To set or change the ssid:
$ sudo apx-hotspot ssid mySSID
# To set or change the passphrase used for authentication:
$ sudo apx-hotspot pass myNewPass1234
# To restart the hotspot service:
$ sudo apx-hotspot reset
# To get the state of the hotspot:
$ sudo apx-hotspot state
{"state":"Enabled","ssid":"mySSID","pass":"myPassword","country":"US","routing":"ppp0"}
# To list the client devices connected to the hotspot:
$ sudo apx-hotspot list
{"stations":[{"mac":"96:f5:bc:51:62:de","rx_bytes":"155189","tx_bytes":"18752","uptime":"79"}]}
# To give internet access using the eth0 as the output interface:
$ sudo apx-hotspot route eth0
# To set the country to Argentina:
$ sudo apx-hotspot country AR
apx-wifi
Tool to manage the wifi interface of the device. Allows you to connect to a wireless network.
sudo apx-wifi <command> [<args=value>]
command | description |
---|---|
start | It enables the WIFI interface and starts the service for connecting with preconfigured networks |
stop | It stops the WIFI service and disables the interface |
restart | It executes a stop-start in the same call |
list | It returns the list of networks configured |
status | It returns a json response with the current state of the wifi service |
scan | It starts a WIFI scan and returns a list of SSIDs |
add [OPTIONS] | Use this option to add a new network to the wifi configuration file. |
remove [OPTIONS] | Use this option to remove a network from the wifi configuration file. |
set [OPTIONS] | Use this option for configuring the wireless interface. |
connect [OPTIONS] | Use this option to connect to a previously configured network. |
version | Returns the tool version |
help | Prints this help message |
options | description |
---|---|
-i , --ip | Use this option for changing the interface IP address and mask. |
-g , --gateway | Use this option for changing the gateway address. |
-d , --dns | Use this option for changing the dns address. |
-f , --default | By using this option the wireless IP address is assigned by the network. |
-s , --ssid | The network identifier. |
-p , --pass | The network password. |
-w , --priority | By default is 0, set higher priority to prioritize as per you need. |
-n , --hidden | Use this flag if the wifi network is hidden |
Example:
# To scan the WIFI network and get the list of SSIDs:
$ apx-wifi scan
# Connect to a previously configured network
$ apx-wifi connect --ssid=mynet
# To add a new network to the configuration file:
$ apx-wifi add --ssid=mynet --pass=mypass --priority=5
# Add a hidden network
$ apx-wifi add --ssid=mynet --pass=mypass --priority=5 --hidden
# To remove a network from the configuration file:
$ apx-wifi remove --ssid=mynet
# To have the wireless IP assigned by the network
$ apx-wifi set --default
# Set the parameters of the wireless interface
$ apx-wifi set --ip=192.168.5.1/24 --gateway=192.168.5.255 --dns=8.8.8.8
# Wi-Fi state
$ apx-wifi status
{"state":"Completed","ssid":"MyAwesomeWifi","signal":"-17","key_mgmt":"WPA2-PSK","mac":"50:33:8B:DD:1E:43","ip":"192.168.1.28","rx_bytes":"871399","tx_bytes":"178166"}
Updated 1 day ago