Linux Environment - FreeWaveTechnologies/ZumIQ GitHub Wiki

For app development, IQ provides a semi-privileged devuser account on the ZumIQ devices, or on the ZumLink devices when the "Custom Apps" license has been applied. Logging in with this account opens a Linux Bash shell prompt. (See the Logging In page for details on logging in.)

The developer environment is based on Debian Linux. In general, documentation, procedures, How-to topics, etc. that apply to Debian Linux and its variants also apply to the ZumIQ development environment. This document contains notable differences.

The developer filesystem is a sandboxed environment distinct from the core system. It is open for read/write by the app developer using sudo as needed. All applications, libraries, config files, etc. use this filesystem.

• Home Directory
• /home/devuser/bin Helper Scripts
• PTP directory
• PTP directory Files
• Manually Accessing the ZumLink CLI
  • Execute the cliBridge Command with NO Arguments
  • Execute the cliBridge Command with a CLI Argument
• Programmatically Accessing the ZumLink CLI

/home/devuser

• The home directory of the devuser account.

/home/devuser/apps

• The recommended location for installing custom user applications.

/home/devuser/apps/template

• Example of what an app directory should look like.
• Contains a sample run script that can be used to launch the application if following the automatic service startup procedure described in App Setup.

/home/devuser/service

• The location for service links that support automatic app startup. (See App Setup for more information.)

/home/devuser/bin

• Contains optional helper scripts that bundle package installation and service setup for some common tools or platforms.

IMPORTANT: These scripts are intended as a jump start for development, and NOT considered as authoritative.

add-service.sh

• Automates the creation of a service directory and run script for an existing app.
• It has been updated to handle the systemctl in FWT2021TP.6 kernel updates.
• See App Setup for an example.

install-buildtools.sh

• Installs compilers and other build toolchain programs and libraries.

install-docker.sh (version 2.0.2 only)

• Installs the the core utilities and libraries for Docker and downloads and installs Docker.

install-essentials.sh

• Installs common tools that are useful to developers.

install-greengrass.sh (version 2.0.2 only)

• Installs the startup scripts for AWS Greengrass. The user still has to download the Greengrass tar.gz file and manually install it.

install-mosquitto.sh

• Installs the Mosquitto MQTT broker service.

install-mysql.sh

• Installs the MySQL database engine service.

install-node-red.sh

• Configures the Node-RED service to run at startup. (Node-RED is included in the developer environment but is NOT enabled by default).
• The default Node-RED location is: http://<ip address>:1880
• Versions prior to 2.0.2 of the RTE, there are two lines in the script are commented out. Line 4 calls npm to re-install Node-RED. This is a leftover from early development, and it is rarely if ever needed. Line 13 calls npm to install additional nodes that may be useful. The nodes may be installed later by selecting Manage Palette from Node-RED's drop-down menu.
• Version 2.0.2 of the RTE, Node-RED is not installed by default in this version of the RTE. This script will download some required libraries and utilities and then install Node-RED software. Run the install-npm-module.sh script prior to running this scrip in version 2.0.2 of the RTE.
• IMPORTANT: There is a known issue when running the default installation of Node-RED on slow or high-latency radio networks. See Node-RED website timeout on slow networks on the Known Issues page for more information.

install-node.sh

• Installs Node.js v6 in version 1.0.6
• Installs Node.js v8 in versions 1.1.0, 1.1.1 and 1.1.2
• Not available in version 2.0.2, since Node.js is already installed. Use apt-get to upgrade the Node.js version.

install-node8.sh (version 1.0.6 only)

• Installs Node.js v8.

install-node9.sh (versions 1.1.0, 1.1.1 and 1.1.2)

• Installs Node.js v9.

install-npm-modules.sh

• Installs a starter pack of Node-RED modules including serial, Modbus, dashboard, and MySQL support, etc.

NOTE: This script may fail the first time it is run with "ENOTFOUND" errors. This is due to an issue with the "serialport" module. Should this occur, running the script a second time will resolve the issue.

install-openPLC (version 1.0.6 only)

EXPERIMENTAL - Attempts to install Open PLC but is dependent upon the underlying OpenPLC code. NOT FOR PRODUCTION USE.

setdate.sh

• Utility script that ensures the system date is set properly by contacting a network time server.

IMPORTANT: The ZumLink and ZumIQ devices do NOT maintain the system date through a power cycle, and must resynchronize with a network time server after a cold boot.

By default, NTP is configured in the ZumLink CLI to contact a network time server. This script is useful only if the default behavior is disabled and NTP must be set up directly.

NOTE: "PTP" refers to the Picture Transfer Protocol upon which file transfer functionality is based.

/ptp

• This is the directory that the user sees as the "ZumLink-##########" PTP device when connected to a computer via a USB cable.
• Files uploaded using the "File Upload" tab in the website appear in this directory.
• Files in this directory are displayed in the "User Data - Drag and Drop Files" tab of the website.
• See Transfer Files for more information on using this directory to upload or download files to the device.
• Files placed here with extensions recognized by the device are automatically be processed. These file extensions are:

NOTE: Some versions of Windows have PTP drivers that do not recognize the the ".pkg", ".cfg", and ".fcf" extensions. Appending ".txt" to the filename will work around this issue and allow Windows to transfer the file to the device.

See detailed information about the individual files in the ZumLink or ZumIQ User Manual.

/ptp/boot_results.txt

• Shows the firmware version the device booted and is currently running.

/ptp/config.txt

• Shows the state of all configurable parameters of the device.

/ptp/fw_upgrade_result.txt

• Shows the status of a device firmware upgrade if one has occurred.

/ptp/help.txt

• Describes CLI commands and configurable parameters of the device.

/ptp/layout.txt

• A YAML-formatted definition of configurable parameters for use by management applications.

/ptp/result.txt

• If present, contains the results of any configuration changes made by copying a .cfg or .cfg.txt file into the ptp directory.

/ptp/sys_info.txt

• Contains device identity properties.

If logged in as "devuser", you can access ZumLink CLI functionality in two ways.

• Execute the cliBridge Command with NO Arguments
• Execute the cliBridge Command with a CLI Argument

• This launches the interactive ZumLink CLI, providing behavior identical to logging in directly as admin:

    devuser@freewave-ib:~$ cliBridge
    FreeWave Shell
    >

• Example: cliBridge txPower
• This executes the CLI command, prints the results to stdout, and returns to the Bash shell:

    devuser@freewave-ib:~$ cliBridge txPower
    FreeWave Shell
    >txPower
    radioSettings.txPower=27dbm
    RESULT:0:OK
    >exit
    devuser@freewave-ib:~$

NOTE: The ZumLink CLI is NOT case-sensitive.

To return to the Linux Bash shell from the CLI, use the exit command:

devuser@freewave-ib:~$ cliBridge
FreeWave Shell
>exit
devuser@freewave-ib:~$

Using the cliBridge command with an argument as described in Manually Accessing the ZumLink CLI provides a programmatic interface with the ZumLink CLI. By programmatically issuing commands and parsing the results, developers can interact with built-in functionality.

A simple program demonstrating this capability is available in the CLI Bridge Example in the repository.