App Development
Application 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.
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 | https://images.site.com/icon.png |
✅ | minApexVersion | Minimum version of Apex OS that's required to run the app | 20.25.00 |
No | repository | Path to app repo | https://www.github.com/path/to/app/ |
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.
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.
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.
- 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/",
- In the repository create a file with the name:
version.json
, with the contents being a key calledstable
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
Updated 9 months ago