Note that some folders are created only after starting the ReadyAgent for the first time, and depends on some modules/features activations

Environment variables

LUA_AF_RO_PATH

This is the location used for software components which must be accessed in read-only by the ReadyAgent (read an write access is ok too). Such files are usually provided as default with the agent.

This path is used by the following RA components and corresponding RA folders:

LUA_AF_RW_PATH

This is the location used for software components which can be accessed in read and write by the ReadyAgent. During its execution, the agent might generate data or might use applications provided by a customer.

Such data must be persisted to be reused later. This path is used by the following RA components:

LUA_PATH

This is the location and the pattern used by the agent to load LUA modules (terminated by .lua extension)

LUA_CPATH

This is the location and the pattern used by the agent to load native LUA modules, usually these modules are shared libraries (.so on embedded linux systems)

AppMon Daemon

Porting work:

Development Needs: No specific development is expected on standard Linux operating system

Other important POSIX API needed (but that are less likely to create permission issues):

getppid

fork

stat (permission error should be related to parameters given to appmon, not the stat function itself)

chdir (permission error should be related to parameters given to appmon, not the chdir function itself)

gettimeofday

waitpid

signal and other related functions: sigprocmask, etc.

alarm

getpwnam

getgrnam

socket and other related functions: close, bind, accept, etc.

Most of the time it will be started by an init script, and given previous user rights requirement, root-like user right is used.

ReadyAgent integration with AppMon Daemon

This is not tested /!\

RA_env.sh

#!/bin/sh#define env variables#put those in different script because they are used by RA start script and init script LUA_AF_RO_PATH=/path/to/readyagent/binaries
LUA_AF_RW_PATH=/path/to/readyagent/working/directory
LUA_PATH="${LUA_AF_RO_PATH}/lua/?.lua;${LUA_AF_RO_PATH}/lua/?/init.lua"LUA_CPATH="${LUA_AF_RO_PATH}/lua/?.so"

init script

#!/bin/shsource(RA_env.sh)# appuser, appgroup: user and group to run regular apps# rauser, ragroup: user and group to run ReadyAgent (this allow to have "privileged" rights for ReadyAgent # using those user rights, AppMonDaemon, ReadyAgent and regular applications can have different rights enabling fine tuning of capabilities. # in this example application process priority are also decreased.
appmon_daemon -a$LUA_AF_RO_PATH/start.sh -w$LUA_AF_RW_PATH-u app_user -g app_group -v rauser -h readyagent -n52>&1| logger -t ReadyAgent &

ReadyAgent start.sh

#!/bin/shsource(RA_env.sh)exportLD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LUA_AF_RO_PATH/lib
# Uncomment this to also get logs on stderr# LOG2STDERR=-s# Run in the runtime directory (access to resources like the "persist"# directory is performed through relative paths).# Also, keep the exit status and divert the logs through "logger".{$LUA_AF_RO_PATH/bin/agent 2>&1; echo$?> ReadyAgent.EXITSTATUS; }| logger $LOG2STDERR-t ReadyAgent
cmd1status=$(cat ReadyAgent.EXITSTATUS)exit$cmd1status

ReadyAgent integration without AppMon Daemon

Most of the time it will be started by an init script, user rights need are to determined after reviewing the whole porting guide to determine ReadyAgent features needed.

Note: If ReadyAgent ApplicationContainter module is used, beware of starting AppMonDaemon before the ReadyAgent.

ReadyAgent features integration

Device Management commands

Those commands are to be sent by Airvantage Platform.

The documentation of all supported commands is in Device Management page.
Here only commands that are likeli to require porting work are listed

ResetToFactoryDefault

This command resets agent settings to factory defaults. All persisted data about agent settings and installed software are lost.
This command is highly dependent on ReadyAgent integration, and although ReadyAgent product provides a generic implementation, the implementation may differ on each different integration of the ReadyAgent.

The implementation of this command is very likely to use LUA_AF_RW_PATH and LUA_AF_RO_PATH Environment variables to locate files to delete / re-init.

Porting work:

Development Needs: The command handler content is likely to need some deve to fit ReadyAgent integration: given a generic implementation (in Lua) is provided, this effort should be simple: add/edit/remove file elements from the list of files to be clean during ResetToFactoryDefault

Integration Needs: ReadyAgent integration must be consistent with what is expected to be reset by ResetToFactoryDefault command (e.g. think about what ReadyAgent files are put on read-only filesystem etc).

ResetToFactoryDefault command handler can be kept at the same place the provided generic implementation is.

Reboot features

In ReadyAgent context, Reboot (without more details) means rebooting the underlying operating system where the ReadyAgent operates.
This can be requested by different means: user API libraries provide a dedicated function, a Device Management command, etc.

Porting work:

Development Needs: No specific development is expected on standard Linux operating system.

Integration Needs: ReadyAgent needs sufficient user rights to call system command reboot, and this command needs to be in the path.

ReadyAgent Logs

simple redirection in syslog is usually a good idea, e.g. in start.sh:

bin/agent | logger -t ReadyAgent

Connection to the Airvantage service platform server

This section may not be included in the "porting" guide

Basically, there are three main reasons for the ReadyAgent to connect to Airvantage service platform server using M3DA protocol:

automatic connection made by the ReadyAgent, to be seen as "polling" connection to retrieve pending jobs (this doesn't trigger data sending to server). This is also known as "heart beat", the configuration of this behavior is done by setting appropriate parameters in server.autoconnect fields in ReadyAgent config. Basically you can have automatic connection on boot, or periodic/cron configured connections (To get more details on autoconnect field, see ReadyAgent ConfigStore page).

a data sending policy triggers and have data to send to the server See the policies definition to understand how it can provoke connection to server.

Please note that in any previous case, if a job is ready for your device on server side, the ReadyAgent will receive it! (at least ReadyAgent always accept jobs from server, it's up to the server to determine when the job is actually ready to be sent to the ReadyAgent)

ReadyAgent id (deviceId) customization

When the ReadyAgent connects to Airvantage service platform server, it sends an identifier that must be unique.
So ReadyAgent integrator must customize this id.

There are two ways to do so:

Setting agent.deviceId field in ReadyAgent Config, for example by updating the defaultconfig.lua file

Implementing the getdeviceid function, enabling to have a dynamic generation of the deviceId (using hardware info for example):

This function need to be global

This function is usually defined in agent.platform module

This function is called only when agent.deviceId is not defined

This function must return the deviceId as a string

The value returned is copied in agent.deviceId in Config store at boot

( thus the value is persisted, and getdeviceid won't be called again until agent.deviceId is reset).