Codex of synaptic interfaces creation

Let me point to several rules that important for keeping in frames of project concept and style:

1. Keep current graphic and layout style. Try to use existed style solutions for your synapse.
2. Keep the same structure for your synaptic interface as shown in currently existed synapses (place images and extra scripts in separate sub-folders).
3. Don't take processor power needlessly. Don't call html processing for each client-side call. Mould tmpl files instead of it.
4. Check dendrite device presence on start.
5. Don't change the main interface frame. Please use just bottominterface.tmpl and maininterface.tmpl.
6. Newer produce popup windows except error alerts (JS).
7. Test it for small screens. Excellent idea to keep minimal horizontal size less than 640px.
8. Your synapse should works without JavaScript. Yes, just on reloads! It should works on any kind of browser.
9. Don't' forget that AXON microserver provides multi-user interface. That means that any user-side JS changes should leads server-side changes in your tmpl interface files (and vice versa).

How to create Synapse and integrate it with AXON microserver

In general, the creation of synapse can be divided into two stages:

1. development of graphical user interface (you can use the available templates) and
2. creation of scripts to control an external devices (dendrites).

Let's consider creation of synapses in example of the 'RFID monitor', available in standard AXON microserver package.

Don't forget to set the local environment as explained in this article and download and untar templates.

1. Directories structure

As you already know from architecture article, all synapses placed in /synapses/{synaptic group}/ sub-folder. So for beginning

1. determine synaptic group, which your synapse is belong to
2. create there directory named exactly like you want name your synapse
3. create empty obligatory files inside that folder:

touch bottominterface.tmpl maininterface.tmpl synapse.css synapse.lua stdout synapse.js

2. CSS layout

Open /sensor.html form templates. There are two fragment market as

<!-- this is a custom bottom interface begin -->
<!-- this is a custom bottom interface end -->

and

<!-- this is a custom synapse interface begin -->
<!-- this is a custom synapse interface end -->

This is a fragments, which refers to main and bottom standard interfaces of the synapse. Best idea is to start mould your html interface right there and copy that in corresponding file (maininterface.tmpl and bottominterface.tmpl) when you finished with layout.

Please pay attention that you need to change paths in CSS on absolute relatively to the root of AXON package after finishing. For example: '../img/rfidsymbols.png' becomes '/synapses/sensory/rfid monitor/img/rfidsymbols.png'

open result it in 'http://localhost' and check it out whether you have everything displaying fine in your new synaptic interface.

3. Server-side scripts API

You synapse.lua micro-engine should have obligatory functions: startsynapse, stopsynapse and redrawinterface

if arg[1] == "startsynapse" or arg[1] == "" or arg[1] == nil then 
end 
if arg[1] == "stopsynapse" then 
end 
if arg[1] == "redrawinterface" then
end 

• startsynapse -- is for starting. Do there everything you need for starting the physical interface. Mould bottominterface.tmpl and maininterface.tmpl. Run daemons if necessary, check device presence, etc...
• stopsynapse -- Stop everthing you need to stop. kill daemons. Change interfaces tmpl back.
• redrawinterface -- this is just for interfaces remoulding. For example in case when user do somethign on client side which mirrors to the interface (don't forget that all synapses provides multiuser interfaces).

in first lines of the synapse.lua script define all common variables which may be necessary to change in case of porting. In case of RFID monitor that was:

deviceString = "_NewRoad_System_PS2_Interface-event" -- this is RFID reader indentifier. check it out by "ls -l /dev/input/by-id/"
event="event1" -- this is a event file of HID device

As you see, functions should calls by arguments. So it's easy to test whether everything works fine. lua synapse.lua [your argument]

Thus, your sunapse.lua should works independently. All other functionality of microengine could be done in the same way.

Handling the errors

All errors could be printed to standard output. Do not be misled with stdout files in each synapse. Thous files are produced by core engine and contains the same output which synapse has been normally printed. It's have two reasons:

1. prevent double calls in multi-user situation
2. give possibility to test and debug each synapse in standalone mode.

Except of that, Lua doesn't produce any debug messages in html format as php does. So, core engine does it by handling this outputs.

JavaScript and client side integration

After debugging your synapse.lua micro-engine and getting it works fine you need to integrate it into the html interface. Core engine has common JS which just caring about synaptic bottom pop-up menu. But it has own copy of jQuery library. So you can easly use jQuery methods in your synapse JS handler too.

Create your handlers. Just keep in mind this several recomendations:

1. core synapse.tmpl provides common path variables (synapticDir, currentSynapticGroup, currentSynapse) which you may can use in your JS script for necessary calls.
2. cause we have a rule of "nonJS" browser supporting, we can handle that paths right in JS. Don't duplicate paths, keep your JS flexible.
3. as I wrote before, don't call your synapse.lua needlessly. save all nesessary data in files to give it read with AJAX calls
4. use setInterval( function() {}, period ); function for synaptic html interface synchronisation (for multi-user purpose)
5. create error handler with alert() output (see details bellow)

This is an example of call of the rfidoutput file, which could be created with RFID daemon each time, when sensor detects new token: currentTag = getData(synapticDir + "/" + currentSynapticGroup + "/" + currentSynapse + "/reader/rfidoutput", ""); // checking for current synapse state

Couple of words about error handling:

As you see, I use this sentence to check for error:

var res = getData ( 'synapse.lua', href );
if ( res.indexOf("Success") == -1 ) alert (res);

Core synapse.lua output all errors or "Success" after all calls. So would be good to handle it with alert(...) message. in the case of RFID monitor it was used on synapse start to message the error of devise detection.

That's all. Last thing: add README file with short instructon if necessary, description of the synapse and don't hesitate to prepare .deb and .ipk packages! (keep the current paths for it "/var/axon/....". Most probably it will not changed in the future) (needs to be documented!). Write here about your synapse and announce it in mailing list.