Mihini/Mihini Agent porting guide

ReadyAgent integration

ReadyAgent files and folders

Default runtime files / folders	Mandatory or Optional	Definition	Description
apps	Mandatory when ApplicationContainer module is activated	LUA_AF_RW_PATH/apps	ApplicationContainer install the applications in this folder
bin	Mandatory	LUA_AF_RO_PATH/bin	RA binaries (agent, appmon_daemon, etc)
itf	Optional	N/A	ReadyAgent doesn't use this folder, you can put it anywhere you want or deleted it. It is provided as placeholder to find interface headers needed to develop application connected to ReadyAgent
lib	Mandatory	LUA_AF_RO_PATH/lib	RA native libraries
lua	Mandatory	LUA_AF_RO_PATH/lua	RA Lua modules (both Lua files and native Lua module). Note: this "lua" folder is the one to be used in LUA_PATH and LUA_CPATH
persist	Mandatory	LUA_AF_RW_PATH/persist	RA settings (Config, TreeManager settings, ...)
resources	Mandatory	LUA_AF_RO_PATH/resources	RA static resources (e.g. TreeManager mapping files)
update	Mandatory when Update module is activated	LUA_AF_RW_PATH/update	Update module uses it to put files to execute SoftwareUpdate
start.sh	Mandatory	N/A	ReadyAgent start up script

Definition Column: see #Environment_variables

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
• Integration Needs:
  • AppMon Daemon needs sufficient user rights to call such Linux services:
    • setgid
    • initgroups (should be same user rights as setgroups)
    • setuid
    • setpgrp
    • umask
    • getpriority
    • nice (at least sufficient user rights to set process priority according to appmon parameters)
    • killpg (depends on the priroty parameters given to appmon)
      
  • AppMon Daemon needs to access to lib folder of ReadyAgent: TBD

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/sh
 
source(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 -n 5 2>&1 | logger -t ReadyAgent &

ReadyAgent start.sh

#!/bin/sh
source(RA_env.sh)
 
export LD_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 the 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

See Reboot features section.

Device Tree

You can expand ReadyAgent Tree (i.e. the Device Tree) by adding new Tree handlers and use them to provide sub tree variables using mapping configuration.

...

ApplicationContainer

ApplicationContainer module requires AppMon Daemon tool to be up and running to correctly operate, so please read AppMon Daemon dedicated section.

Update framework

• Integration Needs:
  • LUA_AF_RW_PATH must not contain the " ' " character.

User API features

swi_sys_Reboot (swi_system C Lib) and system.reboot (Lua API)

Those API are provided to deal with the case of user applications running with restricted user rights but reboot request still need to be done by those applications.

See Reboot Features dedicated section for integration needs.

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, and references to "Airvantage" might get updated to refer to M3DA server instead

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.
• User application are provided with ConnectToServer APIs in airvantage user library (swi_airvantage C library and airvantage Lua module), so user application can manually trigger connection to the 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).

Security parameters for Airvantage communication

TBD