View source for Mihini/Run Mihini on an Open Hardware platform

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

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 <strong>Mihini is still under development</strong>.<br/>

== Step 1 - Build Mihini ==

So far, all the work is being done directly on your remote system. For the following sample, <em>pi</em> user is being used on a <em>RaspberryPi</em> running <em>Raspbian Wheezy</em>. Connect to you device using <code>ssh</code> and follow the steps.
<source lang="bash">
$ ssh pi@raspberry.local
</source>

=== Compilation prerequisites ===

First of all, you will need some compilation tools:<br/>
<source lang="bash">
$ sudo apt-get install build-essential cmake git telnet
</source>

=== 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...] 
<source lang="bash">
$ cd /tmp/
$ git clone ssh://host/mihini.git
</source>

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

<source lang="bash">
# Compile Mihini
$ cd mihini
$ ./bin/build.sh

# Compile Lua
$ cd build.default/
$ make lua
</source>

=== Configure Mihini ===

Then there will be some configuration in <code>build.default/runtime/lua/agent/defaultconfig.lua</code>.
* 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 :))'''
*Enable Lua shell on all network interfaces by <em>adding</em>
** <source lang="lua">shell.address = "*"</source>
* Disable colors while logging , in order to not clutter your syslog.
**<source lang="lua">log.enablecolors = false</source>

=== 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 <code>defaultconfig.lua</code> with the right default settings
* A Linux package, to avoid any kind of compilation or configuration ( It is hypothetical )

<!--
== Step 2 - Configure network connection ==

=== Ethernet connection ===

* Configure/verifiy that there is Ethernet connection as a fall-back

=== 3G connection ===

* <source lang="bash">$ apt-get install ppp</source>
* [http://mycusthelp.net/SIERRAWIRELESS/_cs/AnswerDetail.aspx?sSessionID=&aid=5#Connecting_using_PPPD Connecting using PPPD]
-->

== 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 <code>Appmon</code>. We need to start it.

=== Manually ===

On your device, here a <em>RaspberryPi</em> with user <code>pi</code>.

<source lang="bash">
$ cd mihini/bin/
$ sudo ./appmon_daemon -a /home/pi/mihini/start.sh -w /home/pi/mihini -u pi -g pi -n 5 2>&1 | logger -t Mihini&
</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.

==== Stop Mihini manually ====

<source lang="bash">
$ sudo killall agent
$ sudo killall appmon_daemon
</source>

=== As a service ===

Soon :)

== Step 3 - Setup Koneki environment ==

* Download Lua Development Tools
* 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
** Define your device and configure its <em>"SSH Lua"</em> paths like this [[Image:SshLuaConfiguration.png|center]]
*** 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
LUA_CPATH: /home/pi/mihini/lib/?.so;/home/pi/mihini/lua/?.so
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...)
* 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 <code>main.lua</code>.

<source lang="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()
</source>

= Step 5 - Install your application =

== Manually ==

All you a have to do in order to enable Mihini to handle you application is:
# Create a launcher
# 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 <em>executable file called <code>run</code></em>. Here is its content:

<source lang="bash">
#!/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
</source>

Now the my application folder looks like
<source lang="bash">
$ find raspapp/
raspapp/
raspapp/run
raspapp/main.lua
</source>

=== Install application ===

First of all, I presume you already have an [[#Step_3_-_Start_Mihini_on_your_device|Appmon Daemon running]]. You may wonder which way you can interact with Mihini. While starting, Mihini opens a <code>Telnet</code> server on port <code>2000</code>, it enables you communicate with its runtime. We are about to use it to install an app available at <em>'/tmp/raspapp'</em>, which will be named <em>'sample'</em>, this application will benefit from <em>autostart</em> ( the last <code>true</code> parameter ).
<source lang="bash">$ 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
</source>
We can check that the application is properly installed
<source lang="lua">
> 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
</source>
'''Notice''': <code>CTRL-D</code> to quit.

We can even check logs:
<source lang="bash">
$ cat /var/log/syslog | grep Mihini
</source>
<!-- We may show log output. -->

== 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):
<code>
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"
</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>

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