Syrus 4 Documentation

# Overview

# Architecture

Features:

  • SoC TI ARM Cortex-A8 core processor, AM3358 1GHz.
  • 512MB DDR3 RAM / 4GB 8-bit eMMC Flash storage
  • Micro-SD card slot can support up to 512GB of storage.
  • CAT 4 LTE Modem / Bluetooth BLE 4.2 - SBC +A2DP / WiFi
  • GNSS (GPS, Glonass)
  • Physical interfaces: CAN 1939/RS485/RS232/Ethernet
  • Software packages installed: Python 3.7.6 & Node v12.20.1
  • BLE Version: 4.2

# Software

Besides the python and node development packages, you can install software packages using the apx-core tool:

Core packages

These are the software packages that the device comes installed with: https://apex.digitalcomtech.com/core-packages.txt

Dev packages

These are the dev packages that can be installed: https://apex.digitalcomtech.com/dev-packages.txt

If your application requires software packages outside of these please contact our support team and we'll be glad to assist.

# App Manager

Syrus comes with an application manager tool called syrus-apps-manager that allows you to manage applications and run instances of them with different versioning.

To explain how this works we'll start with a breakdown of the important paths on the file directory:

  • /data/app_data - contains application data and configuration files for your application
  • /data/applications - running instances of applications
  • /data/installed - installed applications
  • /data/logs - standard output and error logging for each application instance

Installing the Application

Once you create an application you can install it using the syrus-apps-manager tool.

syrus-apps-manager install mySampleApp

this creates a folder your application in /data/installed/ followed by the name of the application mySampleApp/ and the version 1.0.0/ (specified in the package.json file). At this point we have installed the application on the device, we have not yet put it to use.

Running the Application

In order to run applications you have to create an instance of them using syrus-apps-manager. Instances are exactly as they sound, independent packaged versions of the application running on the device. To do this we need to specify how we want to call this instance of our application, and what version we want it to run (in case there's multiple versions installed).

syrus-apps-manager create-instance myRunningApp mySampleApp 1.0.0

Internally this will create a symbolic link from the /data/applications folder to the app that was installed under /data/installed

$ ls -l /data/applications

lrwxrwxrwx	1 root	 root	28 	Apr 24 21:24 myRunningApp -> /data/installed/mySampleApp/1.0.0

Output and Error Logs

At this point your application is running and any logging that occurs inside of it can be viewed under /data/logs followed by the name of the instance and the postfix -out.log for standard out, and -error.log for standard error logging.

$ ls -l /data/logs

-rw-r--r--	1 syrus4g  syrus4g		200 Apr 24 19:25 myRunningApp-error.log
-rw-r--r--	1 syrus4g  syrus4g	   1000 Apr 24 20:36 myRunningApp-out.log

User Input/JSON Schema

If your application requires any sort of user input you'll want to add a json schema to the package.json to accomplish this. The json schema builds a form on the Syrus UI's App Manager section that the user can fill out. Once the user saves the form the contents get stored in a hidden file called .configuration.json under /data/app_data/INSTANCE_NAME

$ ls -la /data/app_data/myRunningApp

drwxr-xr-x	3 syrus4g  syrus4g	4096 Apr 13 19:54 .
drwxr-xr-x	8 syrus4g  syrus4g	4096 Apr 15 20:30 ..
-rw-r--r--	1 syrus4g  syrus4g	  27 Apr 13 19:43 .configuration.json
-rw-r--r--	1 syrus4g  syrus4g	  70 Apr  9 19:21 other_config_file.conf

These fields can therefore be accessed with process.env.APP_DATA_FOLDER/.configuration.json

{
	"token": "ABC1234567890"
}

here's an example snippet using js to get the contents of the .configuration.json file.

const fs = require("fs");
const app_data_folder = process.env.APP_DATA_FOLDER;

let filePath = `${app_data_folder}/.configuration.json`;
let configuration = JSON.parse(fs.readFileSync(filePath).toString());
let TOKEN = configuration.token;

# Building an App

In the previous section we walked through what happens when you install an application, now we'll look at how to create an application in the first place.

An overview of what we're going to do:

  • Create a sample application locally on our computer
  • Compress the application
  • Install the application using the Syrus 4 Management Tool Apps Manager
  • Create an instance of the application and run it on the Syrus 4
  • View the logs in the Syrus 4

To get started you'll need to create a package.json file, similar to how you would for a JS/Node project, as well as an init.sh file.

# package.json

Assuming we create an application called MyApp from scratch locally on our computer.

$ mkdir MyApp
$ cd MyApp/

We can use npm init to create the package.json file with the default values.

$ npm init

package name: (myapp) 
version: (1.0.0) 
description: My first app
entry point: (index.js) 
test command: 
git repository: 
keywords: syrus4
author: DCT
license: (ISC) 
About to write to /Projects/dct/apps/MyApp/package.json:

{
  "name": "myapp",
  "version": "1.0.0",
  "description": "My first app",
  "main": "index.js",
  "scripts": {
	"test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
	"syrus4"
  ],
  "author": "user@email.com",
  "license": "ISC"
}

Is this OK? (yes) yes

A valid package.json for Syrus 4 must contain the "name", "version", "description", "main", and "minApexVersion" fields.

required field Description
✅ name Application name, cannot be more than 50 characters
✅ version Application version
No description Description that appears when you install the application on Syrus 4 UI
✅ main Application's main script
No icon Path to an image used as the main icon for the application
✅ minApexVersion Minimum version of Apex OS that's required to run the app
No repository Path to app repo

Example package.json file:

{
	"name": "myapp",
	"version": "1.0.0",
	"description": "My first app",
	"main": "index.js",
	"icon": "https://image.flaticon.com/icons/svg/2948/2948003.svg",
	"minApexVersion": "20.25.00",
	"repository": "https://www.github.com/path/to/app/",
	"scripts": {
		"test": "echo \"Error: no test specified\" && exit 1"
	},
	"keywords": [
		"syrus4" 
	],
	"author": "user@email.com",
	"license": "ISC",
	"dependencies": {}
}

Please note that the name of the application cannot be longer than 50 characters

# index.js

Once you have your package.json specified, you can create your main file index.js and start adding packages and consuming the API.

An example using request

$ npm install request

Create a new file index.js and use this sample code

const request = require("request");
var options = {
	'method': 'GET',
	'url': 'http://localhost:8080/gps/position'
};
request(options, function (error, response) {
	if (error) throw new Error(error);
	payload = JSON.parse(response.body);
	console.log(payload)
});

# init.sh

The init.sh file is a script which indicates the starting point for your application. It's executed anytime that syrus-apps-manager starts your application. Make sure this file is executable (chmod +x init.sh):

Example init.sh file:

node index.js

# Zipping

At this point in your directory you should have

MyApp/
├── index.js
├── init.sh
├── node_modules/
├── package-lock.json
└── package.json

You can now zip your files into a folder and add it using the Syrus 4 Application Manager.

Tip: If you are using Mac you may want to use the zip tool to manually remove unnecessary files from the zipped results.

# view zip info
zipinfo MyApp.zip

# delete a single file from zip 
zip -d MyApp.zip file_to_delete.txt

# remove all files under __MACOSX* directory
zip -d MyApp.zip '__MACOSX*'

Once you have the zipped folder, you can add it to the Syrus 4 using the management UI.

Add App

Install App

Create Instance

Name instance

Start instance

Once you click start you can check the logs:

syrus4g@syrus-867698040012345:$ cat /data/logs/myapplication-out.log

{
  coords: {
	latitude: 25.783675,
	longitude: -80.293561,
	speed: 0.046388926000000004,
	accuracy: 2.9499999999999997,
	altitude: 12.207,
	bearing: 346.74,
	altitudeAccuracy: 4.95
  },
  timestamp: 1619013443,
  extras: {
	hdop: 0.59,
	vdop: 0.99,
	pdop: 1.16,
	fix: 3,
	satsActive: 18,
	criteria: 'signal'
  }
}

Click here to view the project on Github and download the example.

# Versioning

You can have different versions of your application which allow users to view Your application can manage different Automatic versioning can be achieved in two steps.

  1. specify in the package.json a key called repository with a link to your application's repo.
	"repository": "https://www.github.com/path/to/app/",
  1. In the repository create a file with the name: version.json, with the contents being a key called stable and the version is stable.

From there on, the Syrus 4 UI App Manager will display a button for users to click to update to that version, if it detects a newer version than the current one installed on the Syrus, then it will show button with an available upgrade.

{
	"stable": "1.22.0"
}

# User Input / JSON Schema

The schema is an optional object that you can include in the package.json file which will produce forms for your application, allowing you to automatically expose input fields and information via a graphical UI for users to input rather than having them edit any json configuration file.

An example schema is:

{
	...
	"schema": {
		"type": "object",
		"required": [
			"api_token"
		],
		"properties": {
			"account": {
				"label": "User Account Name",
				"description": "Name for the account used in application",
				"type": "string",
				"minLength": 3,
				"maxLength": 50
			},
			"api_token": {
				"label": "Token",
				"description": "Application token",
				"type": "string",
				"fullWidth": true
			}
		}
	}
}

For more information visit JSON Schema Format

# Sample Apps

Last Updated: 5/17/2021, 3:47:04 PM

← API →