Difference between revisions of "Mihini/Run Mihini on an Open Hardware platform"

From Eclipsepedia

Jump to: navigation, search
(Run the compilation)
m (Configure Mihini)
(27 intermediate revisions by 5 users not shown)
Line 21: Line 21:
 
=== Sources to compile ===
 
=== Sources to compile ===
  
Get the sources [NOTE: the source code of Mihini is ''not yet'' available. Still, we wanted to work on this detailed tutorial in parallel of the IP review process...]
+
Get the sources
 
<source lang="bash">
 
<source lang="bash">
$ cd /tmp/
+
$ cd
$ git clone ssh://host/mihini.git
+
$ git clone git://git.eclipse.org/gitroot/mihini/org.eclipse.mihini.git mihini-repo
 
</source>
 
</source>
  
 
=== Run the compilation ===
 
=== Run the compilation ===
  
Lets move into the repository you just cloned. Make sure you have all prerequisites mentioned above installed. Now, simply run the following in the repository you just cloned, here called <code>mihini/</code>.
+
Lets move into the repository you just cloned. Make sure you have all prerequisites mentioned above installed. Now, simply run the following in the repository you just cloned, here called <code>mihini-repo/</code>.
  
 
<source lang="bash">
 
<source lang="bash">
 
# Compile Mihini
 
# Compile Mihini
$ cd mihini
+
$ cd mihini-repo
 
$ ./bin/build.sh
 
$ ./bin/build.sh
  
# Compile Lua
+
# Compile a Lua interpreter
 
$ cd build.default/
 
$ cd build.default/
 
$ make lua
 
$ make lua
 +
# Optional, if you want to use Modbus over serial (e.g. to run the Greenhouse sample)
 +
$ make modbus_serial
 +
 +
# Move the result of the build in your HOME
 +
$ mv runtime ~/mihini
 
</source>
 
</source>
  
 
=== Configure Mihini ===
 
=== Configure Mihini ===
  
Then there will be some configuration on <code>bin/build.default/runtime/lua/agent/defaultconfig.lua</code>.
+
Now there are some configuration items in <code>~/mihini/lua/agent/defaultconfig.lua</code> that you may optionally want to modify.
* Enable the application container
+
 
** <source lang="lua">appcon.activate = true</source>
+
* Enable the update manager
+
** <source lang="lua">update.activate = true</source>
+
 
'''OPTIONAL (but useful :))'''
 
'''OPTIONAL (but useful :))'''
 
*Enable Lua shell on all network interfaces by <em>adding</em>
 
*Enable Lua shell on all network interfaces by <em>adding</em>
 
** <source lang="lua">shell.address = "*"</source>
 
** <source lang="lua">shell.address = "*"</source>
* Disable colors while logging , in order to not clutter your syslog.
+
* Disable colors while logging , in order to not clutter your syslog (log output is shown in /var/log/syslog).
 
**<source lang="lua">log.enablecolors = false</source>
 
**<source lang="lua">log.enablecolors = false</source>
 +
* Enable the highest logfile output level, this way you can easily see errors in the code
 +
**<source lang="lua">log.defaultlevel = "DEBUG" -- default log level: can be one of NONE, ERROR, WARNING, INFO, DETAIL, DEBUG, ALL. See log.lua for details</source>
  
 
=== It should be easier  ===
 
=== It should be easier  ===
Line 60: Line 64:
 
* How to cross compile Mihini from your Desktop machine
 
* How to cross compile Mihini from your Desktop machine
 
* A <code>defaultconfig.lua</code> with the right default settings
 
* A <code>defaultconfig.lua</code> with the right default settings
* A Linux package, to avoid any kind of compilation or configuration ( It is hypothetical )
+
* A Linux package, to avoid any kind of compilation or configuration
  
 
<!--
 
<!--
Line 84: Line 88:
  
 
<source lang="bash">
 
<source lang="bash">
$ cd mihini/bin/
+
$ cd ~/mihini
$ sudo ./appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5 2>&1 | logger -t Mihini&
+
$ sudo ./bin/appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5 2>&1 | logger -t Mihini
 
</source>
 
</source>
  
 
'''Notice''':  we launched <code>appmon_daemon</code> and <code>mihini</code> with <code>root</code> user rights, and applications managed by <code>appmon_daemon</code> will be launched using user <code>pi</code> that should give sufficient user rights for most of needs.
 
'''Notice''':  we launched <code>appmon_daemon</code> and <code>mihini</code> with <code>root</code> user rights, and applications managed by <code>appmon_daemon</code> will be launched using user <code>pi</code> that should give sufficient user rights for most of needs.
 +
 +
'''Possible starting issues'''
 +
The execution of ps aux must show something like the following line to successfully verify that the daemon is running:
 +
<source lang="bash">
 +
root      2360  0.0  0.0  2028  300 pts/0    S+  09:55  0:00 ./bin/appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5
 +
</source>
 +
If this is not the case this may be due to a missing library. Check with ldd bin/appmon_daemon and ldd bin/agent that all required libraries are resolved. If not, try this code
 +
 +
<source lang="bash">
 +
cd /etc/ld.so.conf.d/
 +
sudo /bin/sh -c 'echo "/home/pi/mihini/lib/" > 01-mihini.conf'
 +
sudo ldconfig
 +
</source>
 +
Now the respective ldd commands re-executed should resolve.
  
 
==== Stop Mihini manually ====
 
==== Stop Mihini manually ====
Line 100: Line 118:
  
 
Soon :)
 
Soon :)
 +
WIP lbarthelemy
  
 
== Step 3 - Setup Koneki environment ==
 
== Step 3 - Setup Koneki environment ==
Line 106: Line 125:
 
* Install [http://wiki.eclipse.org/Koneki/LDT/Developer_Area/User_Guides/User_Guide_0.9#Remote_session Remote Development Support for LDT]  
 
* Install [http://wiki.eclipse.org/Koneki/LDT/Developer_Area/User_Guides/User_Guide_0.9#Remote_session Remote Development Support for LDT]  
 
* Configure the remote target in the Koneki environment
 
* Configure the remote target in the Koneki environment
** Define your device and configure its <em>"SSH Lua"</em> paths like this [[Image:SshLuaConfiguration.png|center]]
+
** Define your device and configure its <em>"SSH Lua"</em> paths like this (to reach the presented view, open the Views "Remote Systems" and "Properties". In "Properties" toggle ''Show Advanced Properties'' to true, then select "Ssh Lua" from the "Remote Systems" View) [[Image:SshLuaConfiguration.png|center]]  
 
*** If you want the text version
 
*** If you want the text version
 
<code><pre>LUA_PATH: /home/pi/mihini/lib/?.lua;/home/pi/mihini/lib/?/init.lua;/home/pi/mihini/lua/?.lua;/home/pi/mihini/lua/?/init.lua;./?.lua
 
<code><pre>LUA_PATH: /home/pi/mihini/lib/?.lua;/home/pi/mihini/lib/?/init.lua;/home/pi/mihini/lua/?.lua;/home/pi/mihini/lua/?/init.lua;./?.lua
 
LUA_CPATH: /home/pi/mihini/lib/?.so;/home/pi/mihini/lua/?.so
 
LUA_CPATH: /home/pi/mihini/lib/?.so;/home/pi/mihini/lua/?.so
 
LD_LIBRARY_PATH: $LD_LIBRARY_PATH:/home/pi/mihini/lib</pre></code>
 
LD_LIBRARY_PATH: $LD_LIBRARY_PATH:/home/pi/mihini/lib</pre></code>
* Configure the <em>"Mihini execution environment"</em> (coming soon, will provide nice autocompletion...)
+
* Configure the <em>"Mihini execution environment"</em>
 +
** Download the latest Mihini execution environment [http://download.eclipse.org/mihini/mihini-0.8.zip here]
 +
** Setup this Execution Environment in your LDT environment (Preferences > Lua > Execution Environments))  
 
* Create a launch/debug configuration and test your script.
 
* Create a launch/debug configuration and test your script.
  
== Step 4 - Create your first application ==
+
== Step 4 - Create your first application ==
  
You could blink a LED, use a touch sensor, measure the temperature and available RAM of the board... I decided to keep it simple in this tutorial, my application will simply log :). The file is <code>main.lua</code>.
+
You could blink a LED, use a touch sensor, measure the temperature and available RAM of the board... I decided to keep it simple in this tutorial, my application will simply log&nbsp;:). The file is <code>main.lua</code>.  
  
 
<source lang="lua">
 
<source lang="lua">
Line 127: Line 148:
 
sched.run(main)
 
sched.run(main)
 
sched.loop()
 
sched.loop()
</source>
+
</source>  
 +
 
 +
To run the above example, select the ''main.lua'' file, right-click ''Run As/Lua Remote Application'', it will then be executed on your Raspberry.
  
 
= Step 5 - Install your application =
 
= Step 5 - Install your application =
Line 210: Line 233:
 
SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ENV{ID_VENDOR_ID}=="1199", ENV{ID_MODEL_ID}=="68a3", ENV{ID_USB_INTERFACE_NUM}=="04", SYMLINK+="ttyATConsole1"
 
SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ENV{ID_VENDOR_ID}=="1199", ENV{ID_MODEL_ID}=="68a3", ENV{ID_USB_INTERFACE_NUM}=="04", SYMLINK+="ttyATConsole1"
 
</code>
 
</code>
** For a serial-USB adapter: http://hintshop.ludvig.co.nz/show/persistent-names-usb-serial-devices/
 
* Below is a template of the defaultconfig.lua that you should use to have most of the important features (appmon, updatemanager, ...) of Mihini enabled
 
<code>TODO</code>
 
  
 +
** For a serial-USB adapter: http://hintshop.ludvig.co.nz/show/persistent-names-usb-serial-devices/
 
* Remove Lua comments to save some flash on very tiny devices (could probably be part of the build process btw)
 
* Remove Lua comments to save some flash on very tiny devices (could probably be part of the build process btw)
 
** <source lang="bash">
 
** <source lang="bash">

Revision as of 07:50, 9 April 2013

This page describes a scenario for illustrating the use of Mihini on an Open Hardware Linux-based platform such as BeagleBoard or RaspberryPi.

The goal would be for someone to be able to be only one hour away from taking a bare development board and have it configured to collect data out of the GPIO sensors.

Please bear in mind that Mihini is still under development.

Contents

Step 1 - Build Mihini

So far, all the work is being done directly on your remote system. For the following sample, pi user is being used on a RaspberryPi running Raspbian Wheezy. Connect to you device using ssh and follow the steps.

$ ssh pi@raspberry.local

Compilation prerequisites

First of all, you will need some compilation tools:

$ sudo apt-get install build-essential cmake git telnet

Sources to compile

Get the sources

$ cd
$ git clone git://git.eclipse.org/gitroot/mihini/org.eclipse.mihini.git mihini-repo

Run the compilation

Lets move into the repository you just cloned. Make sure you have all prerequisites mentioned above installed. Now, simply run the following in the repository you just cloned, here called mihini-repo/.

# Compile Mihini
$ cd mihini-repo
$ ./bin/build.sh
 
# Compile a Lua interpreter
$ cd build.default/
$ make lua
# Optional, if you want to use Modbus over serial (e.g. to run the Greenhouse sample)
$ make modbus_serial
 
# Move the result of the build in your HOME
$ mv runtime ~/mihini

Configure Mihini

Now there are some configuration items in ~/mihini/lua/agent/defaultconfig.lua that you may optionally want to modify.

OPTIONAL (but useful :))

  • Enable Lua shell on all network interfaces by adding
    • shell.address = "*"
  • Disable colors while logging , in order to not clutter your syslog (log output is shown in /var/log/syslog).
    • log.enablecolors = false
  • Enable the highest logfile output level, this way you can easily see errors in the code
    • log.defaultlevel = "DEBUG" -- default log level: can be one of NONE, ERROR, WARNING, INFO, DETAIL, DEBUG, ALL. See log.lua for details

It should be easier

What is explained above is just a beginning. We are about to provide material which will speed up previous steps, such as:

  • How to cross compile Mihini from your Desktop machine
  • A defaultconfig.lua with the right default settings
  • A Linux package, to avoid any kind of compilation or configuration


Step 2 - Start Mihini on your device

One of the features of Mihini is to manage the life cycle of your application. In order to do so, applications are run from another program: the Appmon. We need to start it.

Manually

On your device, here a RaspberryPi with user pi.

$ cd  ~/mihini
$ sudo ./bin/appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5 2>&1 | logger -t Mihini

Notice: we launched appmon_daemon and mihini with root user rights, and applications managed by appmon_daemon will be launched using user pi that should give sufficient user rights for most of needs.

Possible starting issues The execution of ps aux must show something like the following line to successfully verify that the daemon is running:

root      2360  0.0  0.0   2028   300 pts/0    S+   09:55   0:00 ./bin/appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5

If this is not the case this may be due to a missing library. Check with ldd bin/appmon_daemon and ldd bin/agent that all required libraries are resolved. If not, try this code

cd /etc/ld.so.conf.d/
sudo /bin/sh -c 'echo "/home/pi/mihini/lib/" > 01-mihini.conf'
sudo ldconfig

Now the respective ldd commands re-executed should resolve.

Stop Mihini manually

$ sudo killall agent
$ sudo killall appmon_daemon

As a service

Soon :) WIP lbarthelemy

Step 3 - Setup Koneki environment

  • Download Lua Development Tools
  • Install Remote Development Support for LDT
  • Configure the remote target in the Koneki environment
    • Define your device and configure its "SSH Lua" paths like this (to reach the presented view, open the Views "Remote Systems" and "Properties". In "Properties" toggle Show Advanced Properties to true, then select "Ssh Lua" from the "Remote Systems" View)
      SshLuaConfiguration.png
      • If you want the text version
LUA_PATH: /home/pi/mihini/lib/?.lua;/home/pi/mihini/lib/?/init.lua;/home/pi/mihini/lua/?.lua;/home/pi/mihini/lua/?/init.lua;./?.lua
LUA_CPATH: /home/pi/mihini/lib/?.so;/home/pi/mihini/lua/?.so
LD_LIBRARY_PATH: $LD_LIBRARY_PATH:/home/pi/mihini/lib
  • Configure the "Mihini execution environment"
    • Download the latest Mihini execution environment here
    • Setup this Execution Environment in your LDT environment (Preferences > Lua > Execution Environments))
  • Create a launch/debug configuration and test your script.

Step 4 - Create your first application

You could blink a LED, use a touch sensor, measure the temperature and available RAM of the board... I decided to keep it simple in this tutorial, my application will simply log :). The file is main.lua.

local log   = require "log"
local sched = require "sched"
local function main()
    log("GENERAL", "INFO", "My first Mihini app is alive :)")
end
 
sched.run(main)
sched.loop()

To run the above example, select the main.lua file, right-click Run As/Lua Remote Application, it will then be executed on your Raspberry.

Step 5 - Install your application

Manually

All you a have to do in order to enable Mihini to handle you application is:

  1. Create a launcher
  2. Provide sources

Create a launcher

Mihini Application container runs executables. To run a Lua application, we need to set some variables beforehand and then lauch your application. In order to do so lets create the proper launcher. In the Mihini world, it is an executable file called run. Here is its content:

#!/bin/sh
 
# Setting up paths
export LUA_PATH="/home/pi/mihini/lib/?.lua;/home/pi/mihini/lib/?/init.lua;/home/pi/mihini/lua/?.lua;/home/pi/mihini/lua/?/init.lua;./?.lua"
export LUA_CPATH="/home/pi/mihini/lib/?.so;/home/pi/mihini/lua/?.so"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/home/pi/mihini/lib"
 
# Running app
/home/pi/mihini/bin/lua main.lua

Now the my application folder looks like

$ find raspapp/
raspapp/
raspapp/run
raspapp/main.lua

Install application

First of all, I presume you already have an Appmon Daemon running. You may wonder which way you can interact with Mihini. While starting, Mihini opens a Telnet server on port 2000, it enables you communicate with its runtime. We are about to use it to install an app available at '/tmp/raspapp', which will be named 'sample', this application will benefit from autostart ( the last true parameter ).

$ telnet localhost 2000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Lua interactive shell
> appcon = require 'agent.appcon'
> = appcon.install('sample', '/tmp/raspapp', true)
2013-01-22 13:33:45 APPCON-INFO: Installing application "sample"
= ok

We can check that the application is properly installed

> for app, t in pairs(appcon.list()) do
+     print( app )
+     for field, data in pairs(t) do
+         print("\t", field, data)
+     end
+ end
sample
                autostart       true
                runnable        true

Notice: CTRL-D to quit.

We can even check logs:

$ cat /var/log/syslog | grep Mihini

Over the air

One day, it will be possible to install application to your remote system Mihini just from its IP, and even more:

  • Use the Koneki tools to create an application package
  • Deploy the package on a publically available web server
  • Connect to the Mihini console and for a connection to the testing server

MISC. TIP & TRICKS

  • You may want to have udev rules so as your USB devices (typically the 3G stick) does not end up having an always changing /dev/ttyUSB<something> file descriptor...
    • For a Sierra 3G stick, create a 99-aircard.rules in /etc/udev/rules.d, with the following rules (your ID_VENDOR_ID and ID_MODEL_ID may be different):

SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ENV{ID_VENDOR_ID}=="1199", ENV{ID_MODEL_ID}=="68a3", ENV{ID_USB_INTERFACE_NUM}=="03", SYMLINK+="ttyATConsole0" SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ENV{ID_VENDOR_ID}=="1199", ENV{ID_MODEL_ID}=="68a3", ENV{ID_USB_INTERFACE_NUM}=="04", SYMLINK+="ttyATConsole1"

  • Remove Lua comments to save some flash on very tiny devices (could probably be part of the build process btw)
    • find . -type f -name '*.lua' -print0 | xargs -0 sed -i '/^[ \t]*--/d'
  • Strip binary code, to save flash too
    •  find . -type f -name '*.so' -print0 | xargs -0 $STRIP_EXECUTABLE_PATH