App Development

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://syrus4.dctserver.com/apex/core-packages.txt

Dev packages

These are the dev packages that can be installed: https://syrus4.dctserver.com/apex/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 are 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": "[email protected]",
  "license": "ISC"
}

Is this OK? (yes) yes

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

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": "[email protected]",
	"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.

🚧

Zipping Contents

Make sure that you zip the files into a folder instead of zipping the folder

Incorrectly Zipped

$ zipinfo MyBrokenApp.zip| grep -v "/."  
Archive:  MyBrokenApp.zip  
Zip file size: 1568567 bytes, number of entries: 1408  
drwx------  2.0 unx        0 bx stor 23-Nov-08 23:42 MyBrokenApp/
1408 files, 4106784 bytes uncompressed, 1218827 bytes compressed:  70.3%

Correctly Zipped

$ zipinfo MyApp | grep -v "/."
Archive:  MyApp.zip
Zip file size: 1308204 bytes, number of entries: 705
-rw-r--r--  2.0 unx    11916 bX defN 21-Apr-21 09:50 package-lock.json
-rw-r--r--  2.0 unx      444 bX defN 21-Apr-21 09:50 package.json
-rw-r--r--  2.0 unx      265 bX defN 21-Apr-21 09:25 index.js
-rwxr-xr-x  2.0 unx       14 bX defN 21-Apr-21 09:26 init.sh
drwxr-xr-x  2.0 unx        0 bx stor 21-Apr-21 09:50 node_modules/
705 files, 3983889 bytes uncompressed, 1150036 bytes compressed:  71.1%

📘

Zip tool in Mac

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

Shell

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

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/",

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

FAQs

Why is my app restarting?

To diagnose why an application is restarting you can look at the /data/core/apex.log . One reasons why it could be happening is that the application is not handling the release of connections to redis correctly.

Apex uses around 45 clients for redis and the limit is 100, this means that if your application is connecting to the redis core and the connections are not being released / closed correctly then it could fail after you reach 100. You will see an error message like this in the logs:

> May 3 14:42:19 syrus-XXX user.crit system-check: redis-core maxclients limit reached, restarting device

Look up redis connection handling on the specific programming language that you're developing with to find more information on how to manage those connections.