Jump to: navigation, search

Mihini/Mihini Agent porting guide

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.
It is provided as placeholder to find interface headers needed to develop application connected to Mihini

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).
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 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

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.

Mihini integration with AppMon Daemon

Warning2.png
This is not tested


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

Warning2.png
This section may not be included in the "porting" guide, and references to "Airvantage" might get updated to refer to M3DA server instead. See bug 402159.


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