Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Mihini/Mihini Agent porting guide"
(→Mihini integration) |
|||
Line 266: | Line 266: | ||
There are two ways to do so: | There are two ways to do so: | ||
− | * Setting '''agent.deviceId''' field in Mihini Config, for example by updating the '''defaultconfig.lua''' file | + | * Setting '''agent.deviceId''' field in Mihini agent Config, for example by updating the '''defaultconfig.lua''' file |
− | * Implementing the | + | * Implementing the <code>getdeviceid<code> function, enabling to have a dynamic generation of the deviceId (using hardware info for example): |
− | ** This function | + | ** This function must be defined in '''agent.platform''' module |
− | + | ** This function is called only when agent Config '''agent.deviceId field is not defined''' | |
− | ** This function is called only when '''agent.deviceId is not defined''' | + | |
** This function must return the deviceId as a '''string''' | ** This function must return the deviceId as a '''string''' | ||
** The value returned is copied in '''agent.deviceId '''in Config store at boot<br> | ** The value returned is copied in '''agent.deviceId '''in Config store at boot<br> |
Revision as of 07:17, 20 June 2013
Contents
Mihini integration
Mihini 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 | Mihini binaries (agent, appmon_daemon, etc) |
itf
|
Optional | N/A |
Mihini doesn't use this folder, you can put it anywhere you want or deleted it. |
lib
|
Mandatory | LUA_AF_RO_PATH/lib | Mihini native libraries |
lua
|
Mandatory | LUA_AF_RO_PATH/lua |
Mihini Lua modules (both Lua files and native Lua module). |
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 | Mihini start up script |
Definition Column: see #Environment_variables
Note that some folders are created only after starting the Mihini agent for the first time, and depends on some modules/features activations
Environment variables
Using Environment variables, it is strongly advised to set value with trailing slash. E.g.: export LUA_AF_RW_PATH=/home/pi/ra/
LUA_AF_RO_PATH
This is the location used for software components which must be accessed in read-only by the Mihini agent (read and 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: all libraries loading and all Lua files loading, and TreeManager mapping files.
LUA_AF_RW_PATH
This is the location used for software components which can be accessed in read and write by the Mihini agent. 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 agent components: ApplicationContainer, agent settings (Config...), Update module ...
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 Mihini: TBD
- AppMon Daemon needs sufficient user rights to call such Linux services:
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 thestat
function itself) -
chdir
(permission error should be related to parameters given to appmon, not thechdir
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.
Mihini integration with AppMon Daemon
mihini_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/Mihini/binaries LUA_AF_RW_PATH=/path/to/Mihini/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(mihini_env.sh) # appuser, appgroup: user and group to run regular apps # rauser, ragroup: user and group to run Mihini (this allow to have "privileged" rights for Mihini # using those user rights, AppMonDaemon, Mihini 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 Mihini -n 5 2>&1 | logger -t Mihini &
Mihini start.sh
#!/bin/sh source(mihini_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 $? > MIHINI.EXITSTATUS; } | logger $LOG2STDERR -t Mihini cmd1status=$(cat MIHINI.EXITSTATUS) exit $cmd1status
Mihini 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 Mihini features needed.
Note: If Mihini ApplicationContainter module is used, beware of starting AppMonDaemon before the Mihini agent.
Mihini 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 Mihini integration, and although Mihini product provides a generic implementation, the implementation may differ on each different integration of the Mihini agent.
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 Mihini 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: Mihini integration must be consistent with what is expected to be reset by ResetToFactoryDefault command (e.g. think about what Mihini 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 Mihini Tree (i.e. the Device Tree) by adding new Tree handlers and use them to provide sub tree variables using mapping configuration. See the Tree Manager documentation.
...
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 Mihini context, Reboot (without more details) means rebooting the underlying operating system where the Mihini agent 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: Mihini needs sufficient user rights to call system command reboot, and this command needs to be in the path.
Mihini Logs
simple redirection in syslog is usually a good idea, e.g. in start.sh:
bin/agent | logger -t Mihini
Connection to the Airvantage service platform server
Basically, there are three main reasons for the Mihini agent to connect to Airvantage service platform server using M3DA protocol:
- automatic connection made by the Mihini agent, 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 Mihini config.
Basically you can have automatic connection on boot, or periodic/cron configured connections (To get more details on autoconnect field, see Mihini 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 Mihini agent will receive it! (at least Mihini always accept jobs from server, it's up to the server to determine when the job is actually ready to be sent to the Mihini agent)
Mihini id (deviceId) customization
When the Mihini agent connects to Airvantage service platform server, it sends an identifier that must be unique.
So Mihini integrator must customize this id.
There are two ways to do so:
- Setting agent.deviceId field in Mihini agent Config, for example by updating the defaultconfig.lua file
- Implementing the
getdeviceid<code> function, enabling to have a dynamic generation of the deviceId (using hardware info for example):
- This function must be defined in agent.platform module
- This function is called only when agent Config agent.deviceId field 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 <code>getdeviceid won't be called again until agent.deviceId is reset).
Security parameters for Airvantage communication
TBD