monomeserial next revision

projects

- CommentAuthorkid_sputnik
- CommentTimeNov 29th 2009
peter, honestly, it probably has more to do with what the developers working on this want to use. personally, I'd go with C++ (creating a service/daemon), because that is what I am comfortable with. between the FTDI API, oscpack and portmidi there is enough x-platform libraries that you would only have to worry about the actual executable and a few other areas (threading and device notification mainly).
- CommentAuthorpeterkirn
- CommentTimeNov 29th 2009
One other thought... having wrangled with JNI, now having a look at this:
http://www.swig.org/

SWIG allows native libraries to be used from *all* the languages mentioned here. ;) Java, Ruby, Python... and even Objective-C is under development.

But first I'd be curious to know what people feel is required for the native library and why. I expect there is a good argument for it, but best to identify that component first, and try to make that as efficient and minimal as possible.
- CommentAuthorpeterkirn
- CommentTimeNov 30th 2009
And PS, Daniel, makes total sense... although it would be great to then get that working with Java, too, so people can integrate these features directly into their code, which is certainly possible with JNI or SWIG.
- CommentAuthorrobb
- CommentTimeNov 30th 2009
I think it should be able to

* route n apps to m monomes
* discover running apps in the subnet automagically
* split monomes, join monome and both
* calibrate tilt
* buffer the display, If I change the cable orientation, I want immediate effects
* give the apps as much information over the connected device(s) as possible
* and more!
- CommentAuthorpeterkirn
- CommentTimeNov 30th 2009
Right, but that sounds to me like:
a) a routing library for serial (sounds like native is best)
b) a set of networking conventions with OSC for multiple connections, which could also be a library (native, Java would both work)
c) an application that uses OSC to talk to the device for all these other functions, with an end-user UI)
- CommentAuthorrobb
- CommentTimeNov 30th 2009
So we need to agree on a feature set and discuss a new protocol for that…
- CommentAuthortehn
- CommentTimeNov 30th 2009
indeed.

i propose possibly splitting some of this functionality up a bit:

1. monomeserial, does most everything it does now and a bit more
2. yet-to-be-named app which is a router/tracker which keeps track of available/open OSC capable apps.

i'll write up some specs/details and use cases promptly.
- CommentAuthormaersk (dovemouse)
- CommentTimeNov 30th 2009
http://www.loop-party.com/
monoroute seems to have some nice features.
- CommentAuthorvisinin
- CommentTimeNov 30th 2009
got a few ideas here.

i've got this libmonome pet project of mine that may be of some use. it's a library written in C that abstracts away the nitty-gritty of the serial protocol and wraps it in a friendlier API. currently, it supports the 40h and series devices, both of which i have successfully tested with it. the platform support is linux (primarily), darwin/OS X, and *BSD (though it's only been specifically tested on openbsd). the only dependency is liblo, which is optional but recommended.

a recent addition to libmonome is the ability to use the same API to communicate over OSC to a running monomeserial instance, effectively abstracting away the fact that OSC is being used at all. liblo/OSC is simply treated as another protocol alongside the series and 40h ones and is used through the same API. this has the added bonus of being able to completely remove OSC from the picture and have an application use the serial device directly (as would be preferable in embedded applications) simply by changing the arguments to the initialization function.

additionally, the fact that the library is written in C makes it immediately usable from many high-level languages with the use of the language's FFI (foreign function interface). this would allow easy usage of libmonome from python, lua, lisp, haskell, whatever.

in my opinion, this is the right way to handle communication. it's one piece of code that manages a very basic thing: the nuts-and-bolts of applications talking to one another (app talking to monomeserial and monomeserial talking to device). by removing raw protocol access of both the serial and OSC sort, amendments to the protocol itself become far more painless. just swap out the system libmonome installation and everything keeps on working.

there's also a commandline version of monomeserial implemented with it more as a proof-of-concept than anything else, though it's the only such application i use (i'm a terminal junkie, i can't help it). a graphical version is simply a matter of picking a toolkit and writing a frontend.

that all being said, here is a paragraph of cons. as it's a pet project still, the functionality that i use is pretty well fleshed-out, and the functionality that i don't isn't much at all. i own a 256, which does not have an accelerometer, and libmonome does not have support for it (though it would be trivial to add, i just haven't done it yet). the monomeserial implementation only has the basics of the OSC protocol and doesn't even support /sys messages. it doesn't run on windows (and i haven't bothered to research porting it). the only documentation is the header file and a few demo apps included in the distribution. bindings for other languages haven't been written yet. cable orientations other than "left" are unsupported.

still, something to think about. the code is adolescent-to-mature, and i'm constantly testing it. it is available under a (very) liberal license at http://github.com/visinin/libmonome . it would be nice to get more eyes on it.

onward (quick little thoughts):

an app<->monomeserial handshake would be cool. offhand i'm more inclined to suggest that the application allocates and assigns itself a port and then informs monomeserial about it because it'd have to be listening on a port for a reply from monomeserial anyway. something feels awkward about having a dedicated "application waiting to get assigned a port" port. overkill, i think.

the application should be informed of the list of monomes and their dimensions. having apps that automatically adapt to monome size would be very cool.

i think serial numbers are sufficient unique identifiers.

JUCE is cool, but I'd be more inclined to suggest wxWidgets or Qt instead. the communities for those toolkits are much, much larger, the development communities larger, and help easier to find.

python is a viable option. in attition to tkinter (with which serial-pyio is written), there's also wxPython and PyQt. it does carry additional requirements, however, namely python itself, the widgetset, and the bindings for the widgetset. wxPython, though, is widely used enough that it would be viable.

we should think about refactoring the OSC protocol (not necessarily *do* it, just think about it). there was a developer of another application (was it VJ software? my memory is hazy) that said it would be better if "/prefix/press <x> <y> <state>" messages were instead "/prefix/<x>/<y>/press <state>". i don't remember much about the discussion, i'll see what i can dig up...

okay, i'm done.
thoughts?
- CommentAuthorloopparty
- CommentTimeNov 30th 2009
I finally had some time to read over this thread from the start, and think there are some important things to consider...

Adding complexity to protocols and interface specifications in general is a mistake. Small changes can often have very big consequences. Mostly here I am talking about the idea of sending polygons or shapes in OSC messages, and so on. For example, when I was implementing MonoRoute I ran into the issue of how to map a 40h app using 'column' messages into a distant corner of a 256 without over-writing the leds on the app next to it. Fortunately I came up with an efficient bit shifting instead of complex maths to do this to keep things running efficiently.

The only real reason I could see for moving away from the current press/column messages would be that they are generating too much traffic. Using MonoRoute I have been able to run Molar 256, 8 instances of boing 40h (mapped 4 to a page), cafe press 256, and live control, without running into too many issues. So at this stage I think creating more complex protocols is not really needed (someone will probably want to debate this though...).

With regards to programming languages, I think it's easy to get lost in a 'tick the box' debate about which language is better. However, it mostly results in lots of talk and little action. I think the first thing that needs to be done is figure out what is the required feature set of the application (without reference to protocols or languages, just functionality).

As far as I can see the requirements seem to be:
- Cross Platform Operation
- Connecting to multiple OSC applications.
- Some form of Auto Port Configuration. (which in my opinion needs some consideration... In the future I expect to be able to post my laptop to a gig and control it from my Monome at home, and if someone only chose to implement a Broadcast/Multicast method, or something that broke through NAT, I would cry ;) )
- What else?? Bring on the ideas!
- CommentAuthorbattery collection
- CommentTimeNov 30th 2009
like all the ideas discussed so far. i'd also like to add the idea of turning MS into a service. have it start up every time you login and then just poll for connections/sleep until a connected monome is detected. make it appear in the menu on a mac, systray for a windows box. if your box frequently runs the same app or set of apps, you likely don't need to configure MS very often. so having it just sit there, waiting for you to connect a monome and do something, would be great.

incorporated into this is catching/killing the popup window that tells you you've disconnected a usb device that's in use (on a mac). it'd suck to have a service running that griped at you all the time.
- CommentAuthorgriotspeak
- CommentTimeDec 3rd 2009
NEVAR FORGET!!!!
- CommentAuthorsam_square
- CommentTimeDec 3rd 2009
>> Just having monomeserial remember the cable orientation would be nice :)
Seconded.
Also, somewhat frequently, on OS X, I can't get MS to come up from it's minimized state and have to end it.

Many thanks.
- CommentAuthormaersk (dovemouse)
- CommentTimeDec 3rd 2009
use cmd+1 i think...and it should pop up.
- CommentAuthorsoundcyst
- CommentTimeDec 3rd 2009
@sam_square,

it's listed in the Window menu as well as cmd+1

also, it should remember the cable orientation.. i'm pretty sure we took care of that a long time ago...
- CommentAuthoremergencyofstate
- CommentTimeDec 3rd 2009
I have the same issue with the monomeserial window disappearing.

Cable orientation is not remembered on the OS X version I use (latest).
- CommentAuthorbattery collection
- CommentTimeDec 3rd 2009
cable orientation works usually for me, but not always.

also, soundcyst, remember when you added "don't care" as an option for led_col and led_row? so that one could apply settings to only half of the row/col on a 256? this doesn't work when you change cable orientation, for some reason. maybe it was never fully added?
- CommentAuthorbar|none
- CommentTimeDec 10th 2009
Have you guys seen this osc bonjour for maxmsp?

http://recherche.ircam.fr/equipes/temps-reel/movement/muller/index.php?entry=entry060616-173626

Allows for applications to register and find each other then negotiate OSC settings automatically.

I'm testing some beta OSC support for another device that uses it and it's slick.
- CommentAuthorJargMarbin
- CommentTimeDec 13th 2009
I'd like the ability to create and assign multiple prefixes to multiple individual descriptions of monome button sets. This way I could control several applications simultaneously.

The interface would be able to add/subtract/edit up to 256 button set descriptions, and each button set description would be one xor more individual button coordinates or one or more ranges of coordinates, or a combination of both of these.
- CommentAuthorloopparty
- CommentTimeDec 14th 2009
I just added some neat functionality to MonoRoute (Beta 3) that might interest you guys. Check it out and see what you think:

http://vimeo.com/8151409
- CommentAuthorbar|none
- CommentTimeDec 14th 2009 edited
@loopparty
fantastic. Looks great!

Question...for apps not connecting to UDP using MAX like Molar, 7up, what about using "oscbonjour" so that we can see monoroute as a zero config bonjour destination. We can then request from you a pair of ports to connect. So Molar and 7up can use oscbonjour to connect automatically to you and autoregister. That way, every app has a unified way of autoregistering automatically.

So flow wise, taking 7up as an example...there would be a "Use Bonjour" option for connecting. When checked...I would have a combo box dropdown of oscbonjour destinations. I would choose "Monoroute" or any other osbonjour enabled destination on the network (This can be remote nodes as well as local nodes). This would configure my osc ports automatically and I would then send you the prefix message via monome protocol over our negotiated ports and 7up would appear just as Strettas apps did. 7up could have used 8080, 8000 but then we'd be stealing the auotregister capability from the MAX layer.

I also kinda feel that MAX apps should use the same approach so everyone is using the same protocol, rather than the MAX layer stealing 8080, 8000 away from everyone else.

I think monomeserial should also be an oscbonjour destination.

I have an example .amxd for how to use "oscbonjour". It is very simple and elegant.

http://recherche.ircam.fr/equipes/temps-reel/movement/muller/index.php?entry=entry060616-173626

[edit] BTW, I think what you have done looks fantastic and a little manual configuration is really no problem. I just wanted to mention the approach above because I'd like to see us all move to a unified way of registering and connecting apps.
- CommentAuthorloopparty
- CommentTimeDec 14th 2009
Thanks Bar|none, the way I have implemented this at the moment is not ideal (because i'm not getting port info from the apps), but I wanted to push ahead to try generate some discussion and interest in the feature. A standardised version of auto configuration is obviously the goal.

Are you able to post the oscbonjour .amxd file? I'd like to have a look at what parts have been implemented.

Whatever method that is chosen will have it's good and bad points, it's just going to be a matter of balancing them for the user and developer. The preference being easy to use and easy to implement.

I noticed also that you used the word "negotiated" when referring to the way Bonjour works. I don't believe there is any negotiation as such, the OSC application just registers to the Bonjour service which holds a name->details mapping (like DNS). So what's your thinking on how MonomeSerial/MonoRoute would talk back to the OSC app?:

1. Would the OSC app and MonomeSerial/MonoRoute also have to register to Bonjour? If so it would need a unique name for every instance of a Max Patch (ie. obo1, obo2, etc). This would get messy as you'd need to know which mapped to which app which requires effort...

2. If it was only the MonomeSerial/MonoRoute side that registered to the service and the OSC app browse and find it (then populate a drop down box). The OSC app then would need to send a /sys/prefix message, and there would also need to be a /sys/oscport message defined as well (which really puts us back at the start).

I have been tossing up whether it just might be easier to have an OSC message that the app just sends to port 8080 (which seems to be the pseudo standard for MonomeSerial listening port, but could also be a varible). The message would just have to contain this type of info:

/sys/oscconfig <prefix> <listening port>

From that MonomeSerial/MonoRoute/etc would know exactly how to talk to the application with zero negotiation, just one message OSC app -> MonomeSerial/MonoRoute.

I've been thinking about what any sort of additional negotation would actually give us and it appears to be very little. I noticed Robb's comments on the first page of this post offering suggestions like this:

[mlr] binds port 23456
[mlr] ----OSC----> [ms:8000] /register "mlr" 127.0.0.1 23456
[ms] binds port 98765
[ms] ----OSC----> [mlr:23456] /registerAcknowledge 127.0.0.1 98765
[mlr] ----OSC----> [ms:98765] /registerAcknowledge

With MonoRoute I have no need for multiple server side ports open, it's always 8080 that accepts all OSC app traffic and acknowledgements really do very little in the case of failure (besides displaying a message that says "registration failed", which would be fairly obvious given that it didn't work).

On the Pure M4L patch side it seems they only really need to ensure that their prefix is unique (per instance, using Stretta's 'thisinstance' methodology) and that they conform to the auto configuration method. This in conjunction with a "/sys/oscconfig <prefix> <listening port>" message would be ridiculously easy, and not have too many draw-backs, besides the user having to ensure that Max and external OSC apps having to have different source ports (eg. 8000, 8001, etc) which usually only requires a one time change. These binding issues are not easy to avoid though without proper execption handling methods (which Max doesn't have).

Interesting topic...
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
I had a look at the Bonjour thing a new years ago in connection with OSC (when Apple were still referring to it as Rendezvous)...

Wow, here we go, February 2005 - did I write this nearly four years ago?

http://www.cassiel.com/space/start/2005-02-22/1

But I think this is, at least in part, a red herring - by and large, it's a cleverer kind of discovery than we need for single-host systems. (It makes lots of sense for multiple hosts.)

The problem we're having, I think, with OSC port setup in MonomeSerial and friends is that the client socket libraries don't have a reply-to-sender feature. I'll need to quickly test some Java, but I suspect that packets from MaxMSP's udpsend do feature the originating port number - it's just that there's no way for using that port to handle the replies. If we had that, then all that would be needed from a centralised router would be a single port number - job done (and then maybe a sprinkling of Bonjour to discover routers).

As I recall, the original CNMAT objects had a facility for reply-to-sender, so it's a shame it's been lost. I have MXJ objects for doing OSC over UDP (and TCP) so could provide rather cumbersome replacements, but that doesn't help existing code, at least not without a bit of find-and-replace.

I've been hacking away at a spec. for an OSC-based router API based on ideas I was formulating pretty much in oblivious parallel to the emergence of MonoRoute - right down to the Beta 3's auto-discovery. I can post the spec here, but it's about 300 lines long...! It does cover things like a handshake to bring up a port-to-port connection for "legacy" applications as well as a session management system. But, as I say, without being able to use originating ports, it's always going to be a bit cumbersome.
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
(i) did I say four years? I meant five. Shit: five years.

(ii) Max's udpsend does indeed bind to an outgoing port. It's high in the unprivileged port space - I'm looking at a 52741 here - and indeed I cannot explicitly create a listener on the same port number.
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
Oh. We're only allowed a limited number of characters per post.

Since the document appears to be nearer 450 lines, including some irrelevant implementation notes, I'm going to have to chop it up a bit and paste it here.

This is very much an "everything but the kitchen sink" approach going into tons of detail. It is very much provisional and open to discussion.

---

* INTRODUCTION

This is an attempt at a specification for a software environment
allowing multiple monome applications to dynamically address an
arbitrary set of physical monome-like devices. The physical monomes
are laid out in whatever orthogonal arrangement the user wants, to
form a virtual grid area (which may contain gaps or overlaps); the
routing specification allows applications to be mapped to this grid,
to the extent that an application's interface area might span multiple
devices, and/or several applications might share (parts of) the same
physical device.

Applications dynamically attach to, and detach from, a common server
which is responsible for driving the physical devices. Each attached
application sees one or more "virtual monome" button grids from which
it receives button presses and to which it sends LED messages. The
sessions containing these virtual monomes may be created and destroyed
dynamically. The application does not need to know where or how (or
even if) these virtual monomes are mapped to physical devices.

A running application communicates with its virtual monome(s) using
messages similar to those used by the current (nonshared) protocol. An
emulation system allows existing applications to run unmodified, and
provides for dynamic OSC channels to be created so that multiple
legacy applications can run side-by-side, even using the same OSC
prefix, sharing the monome grid space.

Alongside the interface used by active monome applications, there is
an "out of channel" protocol which allows virtual monomes to be
positioned and relocated on the physical device grid, and an
interrogation protocol which allows software to gather information
about channels, physical devices, virtual devices, and active
applications. The design aim is to allow programmers, if they wish, to
place interrogation and configuration options into their applications,
but also to allow for separate dedicated applications whose sole
purpose is to manipulate the routing and display environment.

* WHAT THIS SPECIFICATION COVERS

This specification documents:

- the API used by a monome application which will allow it to be
attached to physical devices - this API is very similar to the one
currently in use

- the API for declaring to the driver layer the actual arrangement
of physical monome devices

- the API for dynamically mapping the virtual monomes used by
applications onto the grid of physical devices

- the semantics of the "legacy application" emulation layer, plus the
channel management commands which support it

* WHAT THIS SPECIFICATION DOES NOT COVER

Various topics and issues are out the scope of this document:

- user interface design: the specification provides hooks for all the
configuration and control aspects that might be required, and there
is no reason why other programmers shouldn't implement (multiple,
competing) graphical interfaces to manipulate the routing system

- choice of implementation language or strategy, so long as
implementations conform to the specification and are interchangeable

- application-level control widgets (radio button collections, faders
etc.) - we still consider this to be application-specific, and there
are other libraries (such as our own shado system) which provide
these features

- access to other control hardware (like the tilt sensors in the
monome sixty four)

- low-level driver architecture: for the purposes of the document we
assume a low-level protocol layer which behaves exactly like
multiple instances of MonomeSerial

- (nascent) colour support - our thought is to treat colour (whether
spot-colour as in the APC40 and Launchpad, or RGB colour as in some
Arduinome projects) as an API extension, with a compatibility layer
allowing monochrome virtual monomes to be displayed on a (partly)
colour-enabled device grid.
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
* COMPATIBILITY

At present, an application communicates with a monome over OSC, using
a pair of reasonably standard IP ports: the monome (via its
MonomeSerial interface) is conventionally assumed to be present on
localhost port 8080, and configured to transmit to localhost on port
8000. Each monome has an OSC prefix string (for both sending and
receiving), and MonomeSerial supports commands for dynamically
changing this prefix on a device-by-device basis.

Fortuitously, this API protocol (or at least, the most commonly-used
portions of it) will operate unchanged over a multi-application,
multi-device router, with the following behaviour:

- application sends /[prefix]/message to address a device with prefix
/[prefix] - the router treats the first occurrence of /[prefix] as
an implicit "login", and creates a virtual monome for the
application which can then be mapped to physical devices

- application sends /sys/prefix N /[prefix] - this is a hint to the
router that the virtual monome for the application should be made
visible

* CHANNELS, SESSIONS AND VIRTUAL MONOMES

A channel is a pair of OSC endpoints, one at the router and one at the
application. The router requires at least one channel to accept
commands; additional channels can be created to support legacy monome
applications so that each can use the router on its own OSC ports
independently of other applications.

A channel can be established by or for an application with various
levels of detail, depending on networking requirements. MaxMSP
applications will want to specify a port for incoming packets from the
router, and applications on a different subnet might also want to
specify a routable host name or address for returning packets. In the
simplest case, this information is not needed: the router can return
packets to the same host and port that initiated the connection.

An application "signs in" to the router on a channel. Once attached,
the application can create a new virtual monome session for the
lifetime of the application's execution: the application is expected
to delete the session when it quits. Legacy applications have their
commands emulated so that they behave as if connected to an instance
of MonomeSerial.

There is no reason why an application cannot create multiple virtual
monomes - in fact, the concept of "application" in the API is fairly
meaningless, which is why we use the term "session", where an actual
application might open multiple sessions, each one representing
interaction with a virtual monome grid.

* THE ROUTER API

Right-facing arrows (=->) are messages from application to router;
left-facing arrows are messages from router to application.

** CONTROL CONNECTION MESSAGES

=-> /_router/openchannel [listen-port?] [return-host?] [return-port?]
<-= /_router/openchannel/ok [cid]
(or)
<-= /_router/openchannel/fail
(if there is a problem establishing this channel - and if
there is a route for the reply)

[listen-port?] : if present, treat this call as a request to
open or modify a control connection on a particular listening
port (of use when emulating multiple legacy applications);
otherwise, use the default port, configured in the router

[return-host?] : optional hostname or IP for messages from the
router - default is localhost (127.0.0.1).

[return-port?] : optional port for messages from the router -
default is the originating port of this message

[cid] : an integer uniquely identifying this control route

Set up a control route to the router, specifying an optional new
listen port, return host and return port. The ID [cid], and any
subsequent IDs generated using it, may be referenced on any channel
(so that, for example, interrogation calls are channel-independent).

If the first channel is being opened, the reply is sent to the
specified host and port; otherwise, it is sent to the host and port
from which the command was received.

No two channels can have the same [listen-port] (since the router
would not be able to distinguish between them without examining the
actual originating port); however, channels can have the
same return host/port combination, although the receiving application
would have to distinguish between channels (perhaps by examining the
originating port).

At least two of the optional arguments must be present.

=-> /_router/closechannel [cid]

Close the control channel. [cid] is subsequently invalid. The router's
initial channel cannot be closed (but its remote endpoint can be
redefined).

=-> /_router/listchannels
<-= /_router/listchannels/ok /[cid0] /[cid1] /[cid2] ...

List the currently active channels by ID.

=-> /_router/getchannel [cid]
<-= /_router/getchannel/ok [listen-port] [return-host] [return-port]
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
** APPLICATION MESSAGES

=-> /_router/opensession [w] [h]
<-= /_router/opensession/ok [sid]

Open a connection for a session, creating a virtual monome.

[w] : width of virtual monome
[h] : height of virtual monome

[sid] : an integer uniquely identifying this session

The reply is sent to the return host and return port.

The virtual monome is, by default, mapped at (0, 0) in the grid
space. When created it is invisible, and must be displayed using a
"viewsession" message (below).

=-> /_router/closesession [sid]

Close the session, delete the virtual monome.

[sid] : an integer uniquely identifying this session

Although it is an integer, the id value is used as an OSC prefix in
the conventional OSC messages, which are otherwise unchanged:

<-= /[sid]/press [x] [y] [state]

=-> /[sid]/led [x] [y] [state]
=-> /[sid]/led_row [row] [data0] [data1] [data2] ...
=-> /[sid]/led_col [col] [data0] [data1] [data2] ...
=-> /[sid]/frame [A B C D E F G H]
=-> /[sid]/frame [x y] [A B C D E F G H]
=-> /[sid]/clear [state]

These messages are compatible with the existing MonomeSerial protocol.

The /press messages are relayed to the application on the control
channel that was used to create the session.

** PHYSICAL GRID MESSAGES

These are implementation-specific messages, assuming a router
implementation which uses OSC connections to MonomeSerial servers.

=-> /_router/newdevice [host?] [port] [return-port] /[prefix] [w] [h] [x] [y]
<-= /_router/newdevice/ok [pid]

Create a connection to a physical monome.

[host] : the optional host running MonomeSerial, defaults to
localhost (127.0.0.1).
[port] : the port on which MonomeSerial is listening
[return-port] : the port on which the router should listen
for messages from MonomeSerial
[prefix] : the prefix for the monome device
[w] : the width of the device
[h] : the height of the device
[x] : the device's X position in the grid space
[y] : the device's Y position in the grid space

[pid] : a unique numeric identifier representing a physical
device

Note: this command might be issued multiple times with the same (or
equivalent) host, port and return-port, differing only in prefix, when
addressing a MonomeSerial that is driving several devices.

=-> /_router/deletedevice [pid]

Remove the device connection, closing the incoming network socket if
no other connections are using it. This call causes [pid] to become
invalid.

=-> /_router/listdevices
<-= /_router/listdevices/ok [pid0] [pid1] [pid2] ...

Generate a list of the ids of all attached physical devices.

=-> /[pid]/getinfo
<-= /[pid]/getinfo/ok [w] [h] [x] [y]

Get coordinate information about a device.

=-> /[pid]/movedevice [x] [y]
=-> /[pid]/sizedevice [w] [h]

Change device location or dimensions.

** VIRTUAL GRID MESSAGES

=-> /[sid]/viewsession [how]

Set the session's grid visible (how=1) or invisible (how=0).

=-> /[sid]/top
=-> /[sid]/bottom

Move the session's grid to the top, or the bottom, of the stack.

=-> /_router/listsessions
<-= /_router/listsessions/ok [sid0] [sid1] [sid2] ...

Generate a list of the open sessions.

=-> /[sid]/getinfo
<-= /[sid]/getinfo/ok [w] [h] [x] [y]

Get coordinate information about a session's virtual monome.

=-> /[sid]/movesession [x] [y]
=-> /[sid]/sizesession [w] [h]

Change session virtual monome's location or dimensions. The device
will refresh, but will only cache existing content, even if the
application were painting outside its previous coordinates.
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
* MONOMESERIAL PROTOCOL EMULATION

The router contains an emulation layer allowing it to run existing
monome applications without modification. These coexist with
applications which use the emulator's own protocol.

The emulator interprets /sys/prefix [string] as a hint that an
application using [string] as a prefix is becoming active. The router
creates a new session implicitly, making it visible and bringing it to
the front of the view stack, the first time it sees a new prefix on a
channel; thereafter, sessions are swapped in the visual stack using
/sys/prefix. (This is an attempt to be compatible with naive
applications as well as stretta's use of /sys/prefix for page
swapping.)

OSC prefixes are distinguished according to the control channel on
which they are received; channels are designed so that multiple legacy
applications with the same prefix can use the router independently,
each on its own channel.

The emulator, by definition, has some of the behavioural drawbacks as
MonomeSerial:

- the size of the virtual monomes used by emulated applications is set
statically in the router (although they can be dynamically resized,
as below)

- sessions persist indefinitely (or until deleted by router-specific
messages, as below)

Emulated sessions are manipulated using a lookup call which returns
the "real" session ID for any emulated application's session.

=-> /[cid]/listemulations
<-= /[cid]/listemulations/ok /[prefix0] /[prefix1] /[prefix2] ...

Return a list of the currently emulated sessions.

This is one of the few commands which is prefixed by a channel ID,
since a prefix might be under emulation independently by multiple
channels.

=-> /[cid]/lookupemulation /[prefix]
<-= /[cid]/lookupemulation/ok [sid]
(or)
<-= /[cid]/lookupemulation/fail
(if this prefix is not emulated)

Look up a prefix, returning the router's session ID.

If a session is deleted (via /_router/closesession) the emulation
prefix for that session on its channel is also removed. (A new session
under that prefix will be created if any subsequent messages for that
prefix are received.)
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
Phew, I'm done.

That was too much information.
- CommentAuthorstretta
- CommentTimeDec 14th 2009
Crikey.
- CommentAuthorrobb
- CommentTimeDec 14th 2009
could you attach a pdf so I can go through i it on the train?
- CommentAuthorjul
- CommentTimeDec 14th 2009
Cool ! Thanks.

This should be move to the wiki no ?

Call it RFC then.

This approach maps pretty well with the concept of proxy in serial-pyio. This is what you call "virtual monome".
- CommentAuthorjul
- CommentTimeDec 14th 2009
Having such an RFC is definitely very good on the longer term. Adhering to the RFC will ensure compatibility between apps and routers.

I propose that the various people that participated to this forum (app builders, router/framework developers...) review the document written by Cassiel.

Once the doc is finalized we can go back to the workbench and implement this !
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
@robb - PDF is doable... just gimme a moment to mark it up in LaTeX. (I'm only half-kidding - I almost did that but thought it would end up a little *too* formal. I'm still happy to do so.)

Part of the reason for doing this as an API spec (something RFC-like) was to allow multiple implementations (of the entire system or of portions) - my personal preference is Java, but I like what I've seen of serial-pyio very much so it makes sense to be implementation-agnostic. (Serial-pyio also deals with serial comms already, which is the main reason I steered away from that completely in the spec. - I see it as a different, and already demonstrably solvable, issue.)

That all having been said, I've always believed that a specification is only worth anything if it can be implemented. I'm sure people will be able to look this over and immediately see holes in it - which is good.
- CommentAuthorbar|none
- CommentTimeDec 14th 2009 edited
[edit] Agree totally with cassiel and jul above...you have to make a reference implementation of any protocol before it becomes real.

Here's a simple OSCBonjour example. Yes the ports are not negotiated. Each oscbonjour advertises their host port and ip address though.

So using cassiel's protocol with oscbonjour would produce a zeroconfig solution for the user. But maybe there is simply not enough value in adding oscbonjour. Not sure.

Cassiels Protocol.....

The nice thing about what I see above in cassiels protocol IS a real protocol which is a lot better than what we have now which is a bunch of different routers in between with no unified way for applications to know how to participate.

If a couple of "routers" were to make reference implementations of such a protocol, they would probably learn a lot along the way and I bet a solid protocol would come out. If a couple of the major apps were to also connect to these reference implementations, we'd really have something.

<pre><code>
----------begin_max5_patcher----------
1616.3oc0Zs0aaaCF8YmeED9k9RhsHkHkXAFFV6do.qKCn6s1gAYIlX0IQpo
Koosn+2GuHqXmHESKaKk8fsgjnj+3gmuy2Epuewr4qD2yJmCdM3ifYy99Eyl
oOk5DyZNd17rv6iRCK0CaNm8EwpOO+RykpX2WoOcA35O71qqq1bAdclntJkU
ouKXyYSh0CV9.txcyHuQvq3gYL8U9khjvzMWw7.p9ZNyXfymC9qlKkGVEsNg
e6eWvhpLWMvmtv4Rfefm5Ghq5ajyBm16Q8GUl7M8CChjWt0RS3aLTG049wEW
n95xiCQpiyKY7X4ek+BoYr.BnNNNciONOEePN6Gf5BEv5IdfOT8CzyYPv.7z
ACkJhw63VOugzAMuwX8xN0U+ClL0S6BPBOwduAXvo1cnAP780L.2I2c3PAD+
SMf36hz.hQY3+e.B4TCHTjlZ3EfeY.HZkhOvJtiUTZsbg+fTKnNZt.wOvHVN
8pE0kr1Yu0bhStnAknEM77zvCkNZThLVYY3srmBLrRQ5cLvJVYZRF6JnW6bN
MgyhD0b8.cs1MBexwLitB1U6Mg0wc8HGHlgF.lsptpRvsW.wo242pP9sOevD
pQp.g2vHdDu3b4XHJiVI3eVT2iSgaGySzPVgur4iEQPBLgTIzQS0neuiaSJq
XEfW89v6e0N4WNLuCD5LE0MnQvEOZdG8PnxKX4prx2E5r1IBcxKagXB+RLJu
PTvjypxEEU8ykPVWfm+YJk1.nQv0j1BZ53RxJ7jFGKQFeRAWfHdVn8IzgnmK
7oo1OW7TmVyFmMEixdb4zyaLQuZbw7ouTfkljarGYvmq78Bz0KSm77fGP3dD
4bEtO.ahY4RdgDteUg3KkG.c4jWdPChfQ5e7zHBLX5DfSEgw5bWsNljy.fDq
yNFqicSl7Vt0eeF6BRfC.RRT4BreDAC0QhbGltxfHJ0Yq5q.ZTGS917ckZxk
LdUXUhfu0DAZ5jnoRXne2Imc.f1k1Smvl.U3mRm11V2dUsGPUhAkr57sGYkz
P42lx1toJmK1nxIUonANHZ4IO4HhiAH0LRJZz7QiDYYLd0Sfk2wKqJpiTqgk
eh+I96C+GFnrtfA9pnFrNTlTY0ZF3gHh.4cxJ3gofD4sFllxhWntw0UU4ud4
R4LcMqP9YQRQTX1haJVx925jbV4xJVVd4UELV5xLwcLk4rLqV9.JVlviY2uH
ec9OKOYwW+I82NDGBjbEz2kfHp+h2tVHJM1it3fJAHUU8DGH3fPYlLQOLfq+
vaeSiAGytKIhoFcjfKKgPei2THxzCLtPjChEegqmE+4Z4SSQrK0W7c7jJva1
oAG6TEBzqK+1cGBz1dH5sOQ.S5iZJCU+CTsKKVnAzEOz3PCMYdgLJjPp6g5e
CWfoXXf+Ye6a5uK0csqUvg0OVSS4gHSu4GuBWTyymqOZckv49oKZgaWGczBn
iywDzXSlp6DwcKQjGVa5GVIv9LD0Cxvwle8M2LeXwWNeTu82T7t1.Qugswod
lkKStsPG3zum.6a6P5pIum79S4apMzD2L.O8aRjIxyeHiC860Y1yJFlvDwvC
fPM4fNdBS0xnz0VqIQ1mjTSi6M8eE1SKPNr7X2s9Y00adORrfM0H26gN1baS
j4173+1yVJaakZyupSs4YaPZ+Ylfrkzh26xpYU0z5Xm18wcXYl3aBPPZZx5S
dXSRZIOyZA32L4fpjB.u19TTrCTMc8oATszUoCP0a6WGotdZSSxdGVYxPKkW
ZvrwoL4FoYCxN8UIq+e0JAO50oSa5pyu65QoTFIZybdSiLAOX9wrxpDdq0+w
Gdqv1ZPqShiY7ssurj3bgDBaEE6jcXsMQsvlfzQ0lTupT60lTa9zXhSXavI0
ffiGN4aCeBMtqcDawoCvlnH5BrpYiZQHpGr8nicUUYsn8XsiKQyFtOBOtqoN
13ONx5Vt1x8O.+QB0Swr7Mu9K9A9sGcrVKxFuhw0S00Fa5Qv7dsILU6oRbad
AZ7ZO5XQPeaiI.OXq0OPmNy1GMJX63Jrn1Fn8ifiLGzJkE3KOaBELH+hlZEB
Hv1iNV+BqhWPFWDzp7RF4bJwmAbpISDBb6UU8QGKBdFJTHPpqIMu.SIbADT6
QGowR1QzsmXadi6psM.335TXi5KbbU5Pd1PyFWaxpxQOBKRdvOt3+.HTYR+K
-----------end_max5_patcher-----------
</code></pre>
- CommentAuthorbar|none
- CommentTimeDec 14th 2009
Oh, yeah one other thing...

building a router can be hard. building an app should be easy.

It's like XML. There are only so many people writing parsers and that's a good thing.

The proto needs to be as simple as possible for the app.
- CommentAuthorcassiel
- CommentTimeDec 14th 2009
I did spend a bit of time refining the API specification so that:

- existing "legacy" applications run virtually unchanged

- ancillary code (a bit of OSC exchange) can be added incrementally to aid configuration of a legacy application's connection to a router

- porting an application to the API's "native" protocol is fairly easy (there's a setup and teardown procedure, but all the actual operating messages are completely unchanged)

These were, at least, design aims: I'm sure you folks will be able to tell me how well I've done...!

Re: XML: yes, there aren't that many parsers out there, but (i) there's a working-group specification - of course - and (ii) there are a number of alternate implementations which can be used for interoperability and regression testing. If we only had one "true" implementation we'd be no better than Microsoft Office. Let's not go there.
- CommentAuthorloopparty
- CommentTimeDec 14th 2009
I think i'll digest your spec and comment when I get home from work Cassiel :)

I agree with Bar|none that the most important thing is to have functioning example implementations. We can do this...
- CommentAuthoremergencyofstate
- CommentTimeDec 14th 2009
"Just wanted to tell you good luck, we're all counting on you."

:)
- CommentAuthorcassiel
- CommentTimeDec 15th 2009
When I get a spare moment I'll put this into a new document in the wiki under "tech:".

I suppose we need a name for the API. Lemme see... it's open, it's for the monome, and it's designed for sharing applications and devices. Open Monome Sharing, or OMS?

feeds

monomeserial next revision