Noam Protocol

The Noam protocol is simple and lightweight in order to facilitate the rapid prototyping Noam is designed to support.

Noam messaging utilizes UDP, TCP, and WebSocket protocols for communication in 5 main categories: Discovery, Registration, Event Messaging, Heartbeats, and Host Communications.

UDP is currently used for Discovery broadcasts and Host-to-Host broadcasts, but the UDP framework could be expanded to provide low latency streaming data, and/or compatibility with existing UDP protocols (such as OSC).

For event messaging, data is sent from a Lemma client to Host server, and from Host server to Lemma client. By running servers from both Host and Lemma application, robustness is improved by allowing the Host to directly re-establish a connection to a Lemma to transmit data, and providing extensibility for future implementations of distributed load networks.

WebSocket communication expands Noam compatibility to other platforms (such as browsers), and provides extensibility to communication through network translation layers.

All messages are formatted in JSON to facilitate arbitrarily scalable message complexity and type-less messaging.

Protocol Sequence Diagrams

Discovery, Registration, and Messaging
Heartbeats
Host-to-Host Communications


Discovery

Marco : Lemma Broadcast

UDP broadcast to entire local network at port 1030

Marco Format
[ ”marco”, guest_name , room_name , dialect , lemma_version ]

<guest_name> : The name of the guest the Lemma belongs to.
<room_name> : The name of the room the guest would like to join. If room name is "", the guest is a Free Guest.
<dialect> : The type of guest the Lemma belongs to.
<lemma_version> : The version of the Lemma.

Example Marco
[“marco”,“guest1”,“myRoom”,“java”,“0.2”]

While a Lemma is not connected to a Noam room, it periodically broadcasts Marco messages to the entire local network. Typical broadcast interval is 1 to 5 seconds, depending on the Lemma.

Polo : Response from Host Server

UDP message directed at the IP and port of origin of the Marco message.

Polo Format
[ ”polo”, room_name , tcp_port ]

<room_name> : The name of the room generated by the Host Server.
<host_tcp_port> : The TCP port the Host would like the Lemma to connect to and send data to.

Example Polo
[“polo”,“myRoom”,“7733”]

When a Host Server receives a Marco message from a Lemma it will respond with a Polo message when the Marco:

  • Has a <room_name> field that matches that of the Host’s room.
  • Has a blank <room_name> field (Lemma belongs to a Free Guest), and has been grabbed by the Host (Free Guests are grabbed through the Host’s UI).

Otherwise, the Host will add the Marco’s <guest_name> to its Free Guests or Other Guests lists.


Registration

Registration : Message from Lemma to Host Server

TCP message to <host_tcp_port>, or WebSocket message to 8089

Registration Format
message_length["register", guest_name, guest_tcp_port, hears_list, speaks_list, dialect, lemma_version, options]

<message_length> : The length of the data payload in bytes, padded to 6 characters.
<guest_name> : The name of the guest registering with the Host Server.
<guest_tcp_port> : The TCP port the Lemma serves for the Host to connect to and send data to. (Ignored for WebSocket connections).
<hears_list> : A list of topics the Guest would like to register for.
<speaks_list> : A list of topics the Guest would like to register for. This list is optional – new spoken topics will be automatically added as they’re sent.
<dialect> : The type of guest the Lemma belongs to.
<lemma_version> : The version of the Lemma.
<options> : Optional field for Heartbeat configurations. (Future use: throttling messages)

Example Registration
000112["register","guest1",4423,["topic1","topic2","topic3"],[],”java”,”0.2”,{"heartbeat":"2","heartbeat_ack":"true"}]

When a Lemma receives a Polo message from a Host, it responds with a TCP or WebSocket connection and Registration message. This establishes the Guest as attached to the Host’s Room, and the Lemma stops sending Marco messages.

Registration Options
Optional dict of key-value pair configuration options for the Lemma’s messaging behavior.

“heartbeat” : Contains the heartbeat period in seconds.
“heartbeat_ack” : Boolean field describing if the Lemma wants the Host to respond to heartbeat messages.


Event Messaging

Event : Data Transfer

TCP or WebSocket messages between Host and Lemma on ports established during registration.

Event Format
message_length[ "event", guest_name, event_name, event_value ]

<message_length> : The length of the data payload in bytes, padded to 6 characters.
<guest_name> : The name of the guest registering with the Host Server.
<event_name> : The name of the event message – the ‘Topic’ in the Noam pattern.
<event_value> : The message payload.

Example Event Message
000042["event","guest1","topic1",[1,2,"potato"]]


Heartbeats

Heartbeat : Message from Lemma to Host Server

TCP message to <host_tcp_port>, or WebSocket message to 8089

Heartbeat Format
message_length[ "heartbeat", guest_name ]

<message_length> : The length of the data payload in bytes, padded to 6 characters.
<guest_name> : The name of the guest registering with the Host Server.

Example Heartbeat Message
000022["heartbeat","guest1"]

Heartbeats are optionally enabled via the Registration options field heartbeat key. When a Lemma registers a Guest with a heartbeat period P, the Lemma must send a Heartbeat P seconds after sending its last message or Heartbeat. If the Host does not receive a Heartbeat from the Guest’s Lemma within 2•P seconds of receipt of the last Heartbeat, it will fire the Guest, i.e. remove it from the Your Guests list and close all open connections. A heartbeat period of ~2 sec is a good tradeoff between detecting lost connections and falsely firing Guests.

Upon TCP failure of Heartbeat transmission or being fired by the Host, a Lemma re-enters Discovery mode and begins broadcasting Marcos.

Heartbeat Acknowledgement : Message from Host Server  to Lemma

TCP message on Lemma port established during registration.

Heartbeat Ack Format
message_length[ "heartbeat_ack", guest_name ]

<message_length> : The length of the data payload in bytes, padded to 6 characters.
<guest_name> : The name of the guest registering with the Host Server.

Example Heartbeat_ack Message
000026["heartbeat_ack","guest1"]

Heartbeat acknowledgement, if enabled during Registration, will result in an acknowledgement message sent by the Host Server in response to each heartbeat event.

Ack messages could be used to implement a timeout and serves as to test connection from Host Server to Lemma. Should the message write fail  the host server would discover the connection loss.


Host-to-Host Communications