= Synapse =

[[Image(synapse.png)]]

“Synapses are the connections between neurons in the brain through which nervous impulses pass.”

== News ==

07-10-2010: http://www.internetpapier.nl online for testing. 

22-09-2010: The source code also is avaiable via git on http://code.dyne.org/ . Thanks jaromil!

08-03-2012: We're also pushing to github now: https://github.com/psy0rz/Synapse

09-10-2012: Code is pushed only to github most of the time, so go there to follow the latest changes. 

25-11-2012: It also compiles on the Raspberry, look at the [wiki:projects/synapse/raspberry Raspberry compiling howto]

16-03-2013: Running Media Zapper on the Raspberry pi: https://plus.google.com/108379430172305123363/posts/aG8fPfD7UHL

== Introduction ==

Synapse is an advanced event framework in C++:

 * Modulair plugin system
 * Easy to write modules
 * Easy to send and receive message, while maintaining code readability
 * Session management
 * Build in authentication 
 * Fine grained access control on sending and receiving of events
 * Events can be handled by multiple threads if desired (max-threads is adjustable per session and per module)

== Architecture diagram ==

On an abtract level, Synapse tries to split up the Internet application layer into OSI model layers:

[[Image(layers.png)]]

 * Modules can send and receive arbitrary data via a clean thin C++ API
 * A module can have 1 or more sessions.
 * The module specifys the event they wish to send and the destination session id.
 * The core keeps track of sessions and knows which module(s) to deliver the message to.
 * The core knows which users are allowed or receive the specified event.
 * Modules don't need to be aware of the node they run on.
 * If the session is running somewhere else, one of the connectors transports it to the correct node.
 * Nodes even can be multiple hops away. (e.g. simple routing of messages)
 * This even allows you to build a high performance, high availability cluster without modifying your application.

 * tcp/json connector: 
  * A special module to transparently transport messages to other modules. 
  * Incoming message src is mapped to local session.
 * http/json connector: 
  * A special module to allow javascript instances in browsers to connect and communicate with each other.

== Connector implementation ==

Because of the unique way Synapse is build, the actual connectors can be implemented as modules as well:
[[Image(connectors.png)]]

 * Keeps the core code clean.
 * Easier to debug and maintain.
 * All connectors can only be loaded when needed.
 * The TCP/IP connector is both client and server. Once the connection is established this doesn't matter anymore.

== Other documentation ==

Synapse uses the [http://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern Publish-subscribe pattern].

Whitepaper/notes (still dutch and messy, but nice drawings ;): http://open.syn3.nl/syn3/trac/default/export/latest/trunk/projects/synapse/docs/synapse.odt

Module documentation: https://github.com/psy0rz/Synapse/blob/master/modules/docs/html/index.html


== Download and build ==

Dependencies:
 * libboost-all-dev
 * libcurl4-openssl-dev
 * doxygen
 * libvlc-dev
 * vlc-nox
 * perhaps some others, depending on the modules you need. 

Download:
{{{
psy@r3m0t3h0st ~/test $ git clone https://github.com/psy0rz/Synapse.git synapse
Cloning into synapse...
remote: Counting objects: 3179, done.
remote: Compressing objects: 100% (1498/1498), done.
remote: Total 3179 (delta 2272), reused 2281 (delta 1647)
Receiving objects: 100% (3179/3179), 1.70 MiB | 923 KiB/s, done.
Resolving deltas: 100% (2272/2272), done.


}}}


Configure/compile:
{{{
psy@r3m0t3h0st ~/test $ cd synapse/
psy@r3m0t3h0st ~/test/synapse $ cmake .
...
psy@r3m0t3h0st ~/test/synapse $ make
...
}}}

= Internet paper =

Look at http://internetpapier.nl for a live example.


Create a new drawing and open it in 2 or more browser windows. Let the magic happen.


== running paper yourself ==

Create initial configfiles:
{{{
psy@r3m0t3h0st ~/test/synapse$ echo "{}" > var/paper/config
psy@r3m0t3h0st ~/test/synapse$ echo "{}" > var/paper/index
}}}

Run paper module:
{{{
psy@r3m0t3h0st ~/test/synapse $ ./synapse paper
psy@psylaptop:~/synapse$ ./synapse paper
0xf78540 INFO: Loading config file etc/synapse/userman.conf
0xf78540 INFO: Loading module core from: modules/core.module/libcore.so
0xf78540 INFO: Module loading of core complete.
0xf78540 INFO: Synapse core v1.0 starting up...
0xf78540 SEND module_Init FROM 1:core@core TO broadcast (1:core@core ) (empty)
...
}}}


 * Connect to http://localhost:10080/paper/index.html to see some stuff.
 * Login from a second browser to the paper and see the magic.
 * Use Firebug or Chromium development mode to see the events between the server and browser. (add &synapse_debug in the url)
 * Debug page: http://localhost:10080/synapse/debug.html. 
 * Status page: http://localhost:10080/synapse/status.html. 



= Automatic asterisk operator panel =

This is the first serious project built on top of the synapse platform.

 * Multi server
 * Multi tennant
 * Minimal configuration
 * Auto detection of SIP devices
 * Web based
 * Login is done by calling a special number, so no additional password and user management is neccesary.
 * Tested with configurations generated by: 
  * Asterisk_GUI
  * Thirdlane.
  * FreePBX 

== install instructions ==

 * Compile synapse (no install needed, runs from local directory)

 * Include ''~/synapse.git/modules/asterisk.module/extensions_synapse.conf'' in your dialplan.

 * Add your asterisk server(s) in ~/synapse.git/etc/synapse/asterisk.conf (Also read that file since there are additional config instructions in it. )


 * Start it:
{{{
 psy@ws1:~/synapse.git$ ./synapse asterisk
 
}}}

 * Connect to port http://server:10080/asterisk.html and login by dialing the number.



== Roadmap ==

Current version:
 * Tracking of all calls, channels and sip devices.
 * Html panel that shows all sip devices and channels in realtime.
 * Still read-only
 * Authentication by calling a special number from your sip-device
 * Multi tennant support. 
 * Better user interface.
 * Transfer calls
 * Make calls 
 * Hold/Resume calls.

= Media Zapper =

A Mediaplayer thats a bit like [http://mpd.wikia.com/wiki/Music_Player_Daemon_Wiki Music Player Daemon], but allows you to zap through your media directories in realtime. Also supports video.

[[Image(zapper.png)]]


 * Mediaplayer that has no 'state', no menus and no playlists: it justs plays all your files that are under a certain directory.
 * Usefull if you just want to listen randomly to a part of your music collection without too much trouble.
 * Usefull to quickly navigate and zap through your media.
 * Usefull to quickly zap through your latest movies.
 * Favorites to instantly play your favorite directories with the push of one button.
 * Uses libvlc to play music, videos and streams. (module is done: https://github.com/psy0rz/Synapse/blob/master/modules/play_vlc.module/module.cpp)
 * Runs as a deamon.
 * Realtime web interface, for both desktops and mobile devices. (easy with default synapse http_json module)
 * Controllable by LIRC compatible remote controls. (module is done: https://github.com/psy0rz/Synapse/blob/master/modules/lirc.module/module.cpp)
 * Will also run on the Raspberry and be controllable by cheap RF remote control. (see https://plus.google.com/108379430172305123363/posts/6U7XyiAVXth) Please use HDMI audio output if you want to have decent sound.
 * Uses directories as "play list": (module is done: https://github.com/psy0rz/Synapse/blob/master/modules/pl.module/module.cpp):
  * All the media in the "current" directory will be played recursively, sorted on date, file name, or semi-random.
  * You can switch directorys with a "next dir" and "prev dir" button.
  * You can even enter and exit directories with a "enter dir" and "exit dir" button.
  * Usually you probably will only navigate over your toplevel directorys to select a specific genre of music or navigate to you movie or series dir.
  * There is no need to scan the directorys and build databases in advance.
 * Will probably have more interfaces, like an IRC bot. (should be very easy with synapse)
 * Idea is based on a mp3box prototype i build years ago. (http://paus.sourceforge.net/) I used it all the time and now i'm missing it, so now its time for a more serious version. :)


Mobile web interface: 

[[Image(zappermobile.png)]]


== Running media zapper ==

Make sure you have installed libvlc-dev and boost-dev stuff.

run 
{{{
cmake . && make
}}}

edit ~/synapse.git/etc/synapse/pl.conf and change the path to your media directory. (no trailing slash!)

start it:
{{{
psy@ws1:~/synapse.git$ ./synapse mp

}}}

it should start playing inmediatly

go to http://localhost:10080/mp.html to control it.