What you need

1. An Arduino with Ethernet

Using an arduino with Noam requires an Ethernet connection. That means using an Arduino Ethernet or an Ethernet Shield.

2. The Arduino Lemma

Download the Arduino µC Lemma.

3. Libraries added to the Arduino IDE

Noam currently only works with Arduino IDE 1.0.5 You can download it from the official Arduino site or direct links here: Mac OS X, Windows, Linux 32 bit,  Linux 64 bit

Copy the aJson and LemmaLib directories into your Arduino libraries folder. On OS X, this is typically located inside ~/Documents/Arduino/libraries/. Restart the Arduino IDE.

4. Review the Lemma Example

You can find a simple lemma example in the Arduino IDE under File -> Examples -> LemmaLib -> Examples.

Using the Arduino Lemma

Dependencies

SPI.h, EthernetServer.h, aJSON.h, and Lemma.h are required includes for your Arduino application. SPI and EthernetServer come as part of recent Arduino version contents, so do not need to be downloaded separately.

#include <Arduino.h>
#include "SPI.h"    
#include "EthernetServer.h"   
#include "aJSON.h"  
#include "Lemma.h" 

Instantiate a Lemma

Instantiate a lemma in your sketch before your setup function. guestName is the ID Noam Hosts will associate with your application. If roomName is left blank, the lemma is a Free Guest and may be grabbed by any Host via the Host Interface. Otherwise, it will only join a host with the specified roomName.

Lemma lemma( <guestName> , <roomName> );

Hear Messages

Inside your setup function, register for desired Topics by calling the lemma.hear function. When a an incoming Message on the specified Topic is received, the supplied callback will be called with the Message contents passed as an argument.

void setup() {
    lemma.hear( <topicName> , <messageCallback> );
}

Begin the Lemma

Initialize the lemma inside your setup function.

void setup() {
    lemma.begin( MAC );
    }

MAC = the unique network MAC address for the device. Arduino Ethernet devices come with stickers that have a guaranteed unique MAC address.

Run the Lemma

Run the lemma inside your main loop:

void loop() {
    lemma.run();
}

All incoming messages are checked in the Lemma::run() method, so you should avoid delays in your loop to maximize response time for applications listening for messages.

Outside of your main loop, create a callback for your lemma.hear function calls. Each Topic can be associated with its own callback.

void messageHandler(Message const & message)
{
  //a message has values message.intValue, message.floatValue, message.boolValue, and message.stringValue, which are parsed from the message&#039;s JSON list.  You can also access message.topicName.
}

Speak Messages

To speak a Noam message, from your application:

lemma.speak(<topicName> , <messageValue> );

int, float, bool, and string are the supported data types on Arduino. You can also pass no messageValue and speak a null message to speak simple event signals.

Examples

Hearing messages

Joins an Arduino named “Arduino Guest” to the room “Test Room”. Register to hear messages on topic “FirstName” and prints the value to Serial.

#include <Arduino.h>
#include "SPI.h"   
#include "EthernetServer.h"  
#include "aJSON.h"  
#include "Lemma.h"  

void messageHandler(); //function prototype for callback

static byte MAC[] = { 0xA0, 0xA2, 0xDA, 0x01, 0x7E, 0x59 };  // Network MAC address must be unique on network

Lemma lemma( "Arduino Guest" , "Test Room" );

void setup() {
  Serial.begin(9600);
  lemma.hear( "FirstName", messageHandler );  // Register for Topic &#039;FirstName&#039;, call messageHandler() on new message.
  lemma.begin( MAC );  // example MAC address.
}

void loop() {
  lemma.run();      // check for new Noam messages
}

//
void messageHandler(Message const & message)
{
  Serial.print("Message Received: "); Serial.println( message.stringValue );
}

Speaking messages

Joins an Arduino named “Arduino Guest” to the room “Test Room”. Speaks the message string “Hello World” every 1000mSec on topic “ArduinoSpeaks”.

#include <Arduino.h>
#include "SPI.h"   
#include "EthernetServer.h"  
#include "aJSON.h"  
#include "Lemma.h"  

static byte MAC[] = { 0xA0, 0xA2, 0xDA, 0x01, 0x7E, 0x59 };  // Network MAC address must be unique on network

Lemma lemma( "Arduino Guest" , "Test Room" );

void setup() {
  lemma.begin( MAC );  // unique MAC address.
}

void loop() {
  lemma.run();      // check for new Noam messages
  lemma.speak("ArduinoSpeaks", "Hello World");
  delay(1000);
}

Limitations

Message Rate

Arduinos receiving messages at continuous rates higher than every 200ms may exhibit unstable behavior.

Data Types

Incoming and outgoing message data types supported are: int, float, bool, and string. An update is coming soon to support all primitive types, as well as arrays and potentially key-value maps.

WiFi Shields

WiFi shields are not currently supported, but a port is in the backlog.

Memory

The Lemma uses a large portion of a stanard Arduino’s codespace, so only minimal applications can be implemented on 32k Arduinos.

RAM allocation is configured in the Lemma to a maximum of 128 Bytes for topic names and 128 Bytes for message values.

Developers

If you’re interested in checking out the source or contributing to this Lemma, visit our GitHub repository.