Hub

The NETLab Hub is a stand-alone Java application (cross platform) that handles communications from authoring systems such as Flash and Processing to microcontrollers, MIDI, DMX lighting, OSC, etc. It provides a standard and centralized communications system for your applications.

If you are using the Flash widgets, you don’t need to know much about the Hub, other than that it must be running. Simply launch the Hub and start using the widgets in Flash.

The rest of this page is for people who want to use the Hub independently of the Flash widgets or who simply want to know more about how it works.

Supported Features include:

  • Microcontrollers including Make (via OSC), Arduino (using Firmata) and XBee
  • Devices on an I2C device (using the LinkM USB interface, only BlinkMs currently supported)
  • File I/O
  • Any OSC device
  • Serial Devices
  • Get URL (to retrive the contents of any URL)
  • A plug-in format so external developers can add functionality

Communicating with the Hub

Communications with the Hub are established through Sockets and use the OSC format (but not the formal protocol) for sending commands to the Hub server as well as for receiving data back from it. Since the Hub is fully multi-threaded, it can support multiple connections, even to a single port on the same microcontroller. In effect, each connection becomes a subscriber to the data coming from that single port, and the Hub services the subscribers with a single serial connection to the Arduino.

Setting up a sensor network

Connections to the Hub can also be from remote devices, so that a Hub can be running on one computer with the microcontroller attached, and any computer that can access the Hub’s IP address can communicate with the Hub. As an example of this, we set up a sensor network at the Media Design Program’s space, where a Mac Mini had an XBee base station attached to it with 20 or so remote XBees. Students could access any of the remote XBees by connecting to the Hub running on the Mac Mini from their own computers (in the AnalogIn widget, use the remoteHubID for this).

Example communications with the Hub

To use the Hub to receive values from an Arduino (running Firmata), you would use your language’s method for establishing a socket connection to the Hub at port 51000. Once the connection is established, you would send the following strings to the Hub:

/service/arduino/reader-writer/nlhubconfig/connect /dev/cu.usbserial* 57600\n
/service/arduino/reader-writer/analogin/0/value\n

Note that the strings are terminated with the “\n” as a newline that indicates the end of the command. If you don’t use this, the Hub will not respond to the command.

Once the Hub has established communication with the Arduino, it will be begin sending back values to the requestor. The strings will look like the following, terminated by a NULL (ascii 0).

/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 0
/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 34
/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 288
/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 770
/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 958
/service/arduino/reader-writer/cu.usbserial-A9007ML8/service/arduino/reader-writer/analogin/0/value 1023

It’s imperative that your code handles the NULL terminator at the end of the string returned from the Hub. If you don’t, many language’s string functions will not work correctly when there is a NULL in a string. And the NULL is the only way to know that the message from the Hub is complete.

See the Processing example for an actual code implementation of the above.

Documentation for communicating with the Hub for different devices

_ Arduino » _ OSC software and devices, including the Make Controller » _ XBee » _ BlinkM/LinkM » _ Core services including HTTP Proxy, Fetch URL contents, & file i/o »


**************************************************
USAGE
**************************************************

1. Send a /connect command to a specific service
2. Send a /listen command if you want to receive output from the device
3. Send messages to the device

Example 1 – read from the first analog input port of the arduino

/service/arduino/reader-writer/nlhubconfig/connect
/service/arduino/reader-writer/nlhubconfig/listen /analogin/0/value

Example 2 – set the second digital output port of the arduino to on/true

/service/arduino/reader-writer/nlhubconfig/connect
/service/arduino/reader-writer/digitalout/1/value 1

**************************************************
SUPPORTED CONFIGURATION COMMANDS
**************************************************

Note: the /connect command must be sent before any others

*************************
Command: /service/arduino/reader-writer/nlhubconfig/connect [serial port name] [baud rate (optional)]
Connects to the arduino currently attached to the host computer.
Returns: N/A
Example:
/service/arduino/reader-writer/nlhubconfig/connect /dev/cu.usbserial*
/service/arduino/reader-writer/nlhubconfig/connect /dev/cu.usbserial* 57600

*************************
Command: /service/arduino/reader-writer/nlhubconfig/stoplisten [pin address]
Stops any listeners for the specified pattern received from the connected device.
Returns: N/A
Example:
/service/arduino/reader-writer/nlhubconfig/stoplisten analogout/0/value

**************************************************
SUPPORTED DEVICE COMMANDS
**************************************************

************************
Command: /service/arduino/reader-writer/analogout/[pin]/value [value]
Comment: Writes a PWM value to the specified digital pin
Example:
/service/arduino/reader-writer/analogout/0/value 24

************************
Command: /service/arduino/reader-writer/digitalout/[pin]/value [1|0]
Comment: Turns on or off the specified digital pin
Example:
/service/arduino/reader-writer/digitalout/0/value 1

************************
Command: /service/arduino/reader-writer/analogin/[pin]/value
Comment: Reads the current value of the specified analog pin (0-1023)
Example:
/service/arduino/reader-writer/analogin/0/value

************************
Command: /service/arduino/reader-writer/digitalin/[pin]/value
Comment: Reads the current status of the specified digital pin (0 or 1)
Example:
/service/arduino/reader-writer/digitalin/0/value

Powered by Hackadelic Sliding Notes 1.6.5


**************************************************
USAGE
**************************************************

Example 1 – write to digital output 3 on a Make Controller
with IP address 192.168.1.100:

/service/osc/reader-writer/nlhubconfig/connect 192.168.1.100:10000
/service/osc/reader-writer/digitalout/3/value 1

Example 2 – do a one=time read of the analog input pin 7 on a Make controller
at network address 192.168.1.100:10000

/service/osc/reader-writer/nlhubconfig/connect 192.168.1.100:10000
/service/osc/reader-writer/nlhubconfig/listen /analogin/7/value
/service/osc/reader-writer/analogin/7/value

Example 3 – read stream of all messages matching the pattern “/analogin/7/value”
received on port 30000 from an OSC device at network address
192.168.1.100:10000 (poll at 5 samples per second):

/service/osc/reader-writer/nlhubconfig/connect 192.168.1.100:10000 30000
/service/osc/reader-writer/nlhubconfig/listen /analogin/7/value 1 5

**************************************************
SUPPORTED CONFIGURATION COMMANDS
**************************************************

Note: the /connect command must be sent before any others

*************************
Command: /service/osc/[name]/nlhubconfig/connect [ip:sendport] [receiveport (optional)]
Returns: N/A

Connects to an OSC device. Send port is used for receiving if no receiveport specified.
Sending this command when the service is already connected will automatically close
the existing connection and re-open a new one. Issuing the /connect command to a currently
connected device will remove all current listeners and stop any polling before reconnecting.
NOTE: For now, if using the Make Controller then the receiveport and the port in the deviceaddress MUST BE THE SAME.
See http://www.makingthings.com/ref/firmware/html/group___network_o_s_c.html (osc_udp_port property)

Example:
/service/osc/reader-writer/nlhubconfig/connect 192.168.1.100:10000
/service/osc/reader-writer/nlhubconfig/connect 192.168.1.100:10000 20000

*************************
Command: /service/osc/[name]/nlhubconfig/listen [pattern] [1 | 0 (optional)] [rate (optional)]
Returns: N/A
Comment: Asks the service to listen to message matching a given pattern. If argument 2
is non-zero then an autopoll thread will be started at the specified sample rate (in samples per second).
The autopoll option is useful for devices such as a Make controller that require polling in
order to return values.
Example:
/service/osc/polling-reader/nlhubconfig/listen /analogin/7/value
/service/osc/polling-reader/nlhubconfig/listen /analogin/7/value 1 10

**************************************************
SUPPORTED DEVICE COMMANDS
**************************************************

*************************
Command: /service/osc/[servicename]
Returns: Nothing
Comment: Simply starts the service without doing anything else (see example below)
Example:
/service/osc/reader-writer

*************************
Command: /service/osc/[servicename]/[osc command path supported by device]
Returns: depends on command
Comment: Sends everything after [servicename] to the device
Example:
/service/osc/reader-writer/digitalin/0/value (sends /digitalin/0/value to the device)

Powered by Hackadelic Sliding Notes 1.6.5

**************************************************
USAGE
**************************************************

1. Send a /connect command to a specific service
2. Send messages to the device

Example 1 – read from the first analog input port of remote xbee address 21

/service/xbee/reader-writer/nlhubconfig/connect /dev/cu.usbserial*
/service/xbee/reader-writer/21/analogin/0/value

Example 2 – read from the second analog input port of any remote xbee that is sending messages

/service/xbee/reader-writer/nlhubconfig/connect /dev/cu.usbserial*
/service/xbee/reader-writer/*/analogin/1/value

**************************************************
SUPPORTED CONFIGURATION COMMANDS
**************************************************

Note: the /connect command must be sent before any others

*************************
Command: /service/xbee/reader-writer/nlhubconfig/connect [serialport]
Returns: N/A

Connects to the XBee network currently attached to the host computer. Settings are
specified in the SystemProperties section of this configuration file.

**************************************************
SUPPORTED DEVICE COMMANDS
**************************************************

NOTE: all remoteid values are treated as Hex literals.

*************************
Command: /service/xbee/reader-writer/[remoteid]/analogin/[pin]/value
Returns: the current value of the specified analog input pin
Example:
/service/xbee/reader-writer/21/analogin/0/value

Listens for input on the specified analog input port on the specified device.
Remote id supports wildcard using the ‘*’ character.

*************************
Command: /service/xbee/reader-writer/[remoteid]/digitalin/[pin]/value
Returns: the current state (0 or 1) of the specified digital input pin
Example:
/service/xbee/reader-writer/21/digitalin/0/value

Listens for input on the specified analog input port on the specified device.
Remote id supports wildcard using the ‘*’ character.

*************************
Command: /service/xbee/reader-writer/[remoteid]/digitalout/[pin]/value [1 or 0]
Example:
/service/xbee/reader-writer/21/digitalout/0/value 1

Turns on or off the specified digital pin.
Remote id supports wildcard using the ‘*’ character. If wildcard is supplied as
remote id then the write will be broadcast to all remote xbees.

Powered by Hackadelic Sliding Notes 1.6.5


**************************************************
SUPPORTED CONFIGURATION COMMANDS
**************************************************

Note: the /connect command must be sent before any others

*************************
Command: /service/linkm/reader-writer/nlhubconfig/connect
Connects to the linkm currently attached to the host computer.
Returns: N/A

**************************************************
SUPPORTED DEVICE COMMANDS
**************************************************

************************
Command: /service/linkm/reader-writer/fadetorgb [I2C address] [r] [g] [b]
Comment: Fades the linkm LED at the specified address to the given rgb value
Example (fade LED 9 to white):
/service/linkm/reader-writer/fadetorgb 9 255 255 255
Example (fade LED 9 to black):
/service/linkm/reader-writer/fadetorgb 9 0 0 0

************************
Command: /service/linkm/reader-writer/setfadespeed [I2C address] [speed (1-255)]
Comment: Sets the fade speed of the linkm LED at the specified address
Example (set LED 9 to instantaneous fade):
/service/linkm/reader-writer/setfadespeed 9 255
Example (set LED 9 to slowest fade):
/service/linkm/reader-writer/setfadespeed 9 1

Powered by Hackadelic Sliding Notes 1.6.5


======================
Dump services config
======================
Dumps config when any command is sent.
e.g. /service/core/list-services

======================
Pipe
======================

Supported commands:
/service/core/pipe/nlhubconfig/connect [port] [send|receive|send-receive]
/service/core/pipe/value (returns latest value from pipe)
/service/core/pipe/value [value] (sends a value to pipe)
e.g.
/service/core/pipe/nlhubconfig/connect myport send
/service/core/pipe/value
/service/core/pipe/value foo

======================
HTTP Proxy
======================

Connect to this service via a web browser using the following URL:

http://localhost:[port]?port=[remotePort][&cmd=[cmd]][&listen=[true|false]]

e.g. http://localhost:8080?port=1999
e.g. http://localhost:8080?port=9001&cmd=/analogin/0/value
e.g. http://localhost:8080?port=9002&cmd=/servo/0/position 30&listen=false

NOTE: the proxy is asynchronous, so it is really only suitable
for use with either writes or one-time reads. If you fail to send
a “listen” parameter, the proxy assumes that you want to listen for
a response from the remote service. If the remote service fails to
respond then the proxy will time out and close the connection.

======================
Fetch URL contents
======================

Supported commands:
/service/core/curl/get [the URL]
e.g. /service/core/curl/get http://www.google.com

=======================
File I/O
=======================
Command format: /service/core/file-io/[command] [arg]

Supported commands:
/service/core/file-io/base [path to directory]
/service/core/file-io/filename [filename]
/service/core/file-io/get (returns the contents of the file)
/service/core/file-io/put [string] (replaces the contents of the file with the string)
/service/core/file-io/append [string] (appends the string to the file on a new line)

NOTE: The string argument to the put and append commands needs to be double-quoted
if it contains more than one token; e.g. /filesystem/put “Hello world.”

Powered by Hackadelic Sliding Notes 1.6.5

Last modified May 30th, 2012