Codex of synaptic interfaces creation

Let me point out the several rules that are important to keep the project concept and style:

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

How to create a synapse and integrate it with AXON microserver

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

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

Let's have a look at creation of synapses on the 'RFID monitor' as an example, available in a standard AXON microserver package.

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

1. Structure of directories

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

1. determine a synaptic group, to which your synapse belongs
2. create there a directory named exactly like you want to 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 from the templates. There are two fragment markers

<!-- 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 -->

These are the fragments, which refer to the main and bottom standard interfaces of the synapse. The best idea is to start moulding your html interface right there and copy that into the corresponding file (maininterface.tmpl and bottominterface.tmpl) when you are finished with the layout.

Please note, that you need to change paths in CSS into absolute paths relative to the common directory after you complete. For example: '../img/rfidsymbols.png' becomes '/synapses/sensory/rfid monitor/img/rfidsymbols.png'

Open the result in 'http://localhost' and check whether everything is displayed fine on your new synaptic interface.

3. Server-side scripts API

Your synapse.lua micro-engine should have the 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 -- Start. Indicate there everything you need to start the physical interface. Mould bottominterface.tmpl and maininterface.tmpl. Run daemons, if necessary, check for the presence of a device, etc...
• stopsynapse -- Stop everything you need to stop: kill daemons, change interfaces tmpl back.
• redrawinterface -- It's just for the interfaces remoulding. For example, in case user did something on a client side that had an effect on the interface (don't forget that all synapses provide multi-user interfaces).

Use the first lines of synapse.lua script to define all common variables, which may be a subject to change in case of porting. In case of RFID monitor it looks like this:

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

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

Thus, your sunapse.lua should work independently. All other functionality of microengine could be done likewise.

Handling the errors

All errors could be printed to a standard output. Do not be misled by stdout files in each synapse. Those files are produced by the core engine and they contain the same output, which synapse prints normally. There are two reasons:

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

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

JavaScript and client side integration

After debugging your synapse.lua micro-engine and getting it to work fine, you need to integrate it into the html interface. The core engine has a common JS, which just cares about synaptic bottom pop-up menu, but it has its own copy of jQuery library. So, you can easily apply jQuery methods to your synapse JS handler too.

Create your handlers. Just keep in mind these several recommendations:

1. core synapse.tmpl provides common path variables (synapticDir, currentSynapticGroup, currentSynapse), which you can use in your JS script for necessary calls.
2. since we have a rule of "nonJS" browser supporting, we can handle that paths right in JS. Do not duplicate paths, keep your JS flexible.
3. as I wrote before, do not call your synapse.lua needlessly. Save all necessary data in the files to be read with AJAX calls.
4. use setInterval( function() {}, period ); function for a synaptic html interface synchronization (for multi-user purpose)
5. create an 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 a new token: currentTag = getData(synapticDir + "/" + currentSynapticGroup + "/" + currentSynapse + "/reader/rfidoutput", ""); // checking for a current synapse state

A couple of words about error handling:

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

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, it would be good to handle it with alert(...) message. In case of RFID monitor, it was used on synapse start to indicate an error of devise detection.

That's all. The last thing: add README file with a short instruction, if necessary, that includes description of the synapse, and don't hesitate to prepare .deb and .ipk packages! (keep the current path for it "/var/axon/....". Most probably it won't be changed in the future) (it needs to be documented!). Write there about your synapse and announce it in the mailing list.