Documentation Wiki rss-feed

Illuminator


Name

Illuminator:

image:illuminator_expanded.png

8641
illuminator

Description

Illuminator is an agent that enables the creation of lighting patterns on the Eigenharp keyboard. The positioning of the individual lights using columns, rows, courses or keys is described in the Keygroup section.

Ports

Key input

114 116
key input

  • Input
  • Type: Key

The key input is used during choose mode as described below. It is typically connected to a Keygroup Output Key Output port.

Musical light map

8638 3122 8826
musical light map

  • Input,Set,Output
  • Type: String

The Musical Light Map describes the musical lighting pattern. Musical and physical positioning is described in the Keygroup section.

The light map describes the current lighting pattern, modifying it is more convenient with the verbs that are described below. The format of the musical light map description is as follows:

[[[course,key],colour],[[course,key],colour],...]

Where course and key define the position of the light and colour can be either red, green or orange.

Physical light map

8637 3122 8826
physical light map

  • Input,Set,Output
  • Type: String

This Physical Light Map describes the physical lighting pattern, see the Musical Light Map above for more information.

Light output

3122 125
light output

  • Output
  • Type: Light

The light output provides the lighting pattern that is active in the Illuminator, this is typically connected to a Light Input port on a Keygroup output, a Keyboard, or other agents that accept light input.

Server port

8642 1822
server port

  • Input,Set,Output
  • Type: Number
  • Range: 0 to 65535

The TCP/IP port number that the built-in HTTP server will use when it's started. Note that ports below 1024 are usually only accessible by the operating system so it's best to choose numbers that are higher. Be aware that there's always a possibility for the port to be used by another application.

Server start

8642 56
server start

  • Input,Set,Output
  • Type: On/Off

When set to On, starts the built-in HTTP server. The server is stopped when set to Off.

Server status output

8642 8754 125
server status output

  • Output
  • Type: Number
  • Range: 0 to 5

Indicates the on/off status of the built-in HTTP server.

Web Console

It's possible to display and scroll text remotely by using the Illuminator's web console. This can for instance be used by and assistent to display real-time messages on the Eigenharp Alpha for audience interaction.

To access the web console, use a regular web browser and connect to:

http://hostname:serverport

where hostname should be the name or IP address by which the computer running EigenD is known on the network and serverport should be the server port of the Illuminator agent.

image:illuminator_web_console.png

Verbs

Set:

67
set

The 'set' verb is used to set a light to a certain colour.

Un Set:

6 67
un set

The 'un set' verb is used to clear a light.

Choose:

122
choose

The 'choose' verb is used to use keys to select lights of a certain colour.

Un Choose:

6 122
un choose

The 'un choose' verb is used to cancel choose mode without making any changes to the light map.

Clear:

228
clear

The 'clear' verb is to clear the whole light pattern from the Illuminator.

Server Start:

8642 56
server start

The 'server start' verb is to start the built-in HTTP server.

Server Stop:

8642 57
server stop

The 'server stop' verb is to stop the built-in HTTP server.

Server Toggle Start:

8642 441 56
server toggle start

The 'server toggle start' verb is toggles the built-in HTTP server on or off based on if it's currently running or not.

Save:

174
save

The 'save' verb stores the current Illuminator lights as a pattern that can be recalled later.

Load:

167
load

The 'load' verb restores lights that were previously stored.

Delete:

1424
delete

The 'delete' verb removed previously stored lights.

Examples

Before using the Belcanto commands below, make sure you have the desired Illuminator Agent in the conversation using

8641 ? 1131
illuminator X listen

where X is the number of the desired Illuminator Agent.

Set a physical light to a certain colour

The set a physical light to a certain colour, use

1156 ? 8612 ? 23 ? 67
column X row Y to Z set

where X is the column number, Y is the row number and Z is the colour: red, green or orange.

Set a musical light to a certain colour

The set a musical light to a certain colour, use

1471 ? 114 ? 23 ? 67
course X key Y to Z set

where X is the course number, Y is the key number and Z is the colour: red, green or orange.

Clear a specific physical light

To clear a physical light, use

1156 ? 8612 ? 6 67
column X row Y un set

where X is the column number, Y is the row number

Clear a specific musical light

To clear a musical light, use

1471 ? 114 ? 6 67
course X key Y un set

where X is the course number, Y is the key number

Clear all physical lights

To clear all physical lights, use

8637 228
physical clear

Clear all musical lights

To clear all musical lights, use

8638 228
musical clear

Choose physical lights on the keyboard

To start choosing physical lights on the keyboard, use

8637 65 ? 122
physical as X choose

where X is the colour: red, green or orange

To confirm the selection made in choose mode, tap the last key you pressed a second time. This will exit choose mode and add the selection to the existing light map.

Choose musical lights on the keyboard

To start choosing musical lights on the keyboard, use

8638 65 ? 122
musical as X choose

where X is the colour: red, green or orange

To confirm the selection made in choose mode, tap the last key you pressed a second time. This will exit choose mode and add the selection to the existing light map.

Leave choose mode and discard the selection

To leave choose mode by preserving the current light map and discarding the current selection, use

6 122
un choose

Store the current lights

To store the currently displayed lights, use:

174
save

the pattern will the stored with the next available number. The pattern will be available as 'light mapping X', where X is the number that was used.

Store the current lights with a particular number

To store the currently displayed lights, use:

? 174
X save

where X is the number that will be used to refer to the stored pattern, the pattern will be available as 'light mapping X'.

Store the current lights with a particular Belcanto name

To store the currently displayed lights, use:

? 174
X save

where X are valid Belcanto words, thet will be used to refer to the stored pattern.

Load a stored light pattern

To restore a previously saved light pattern, use:

? 167
X load

where X is the Belcanto name and/or number that identifies this pattern.

Remove a stored light pattern

To remove a previously saved light pattern, use:

? 1424
X delete

where X is the Belcanto name and/or number that identifies this pattern.

Advanced HTTP server REST control

The Illuminator agent can be controlled remotely over HTTP using a REST architecture.

Note that this is very low-level and intended for software developers to control Illuminator from the outside world. We provide more user-friendly control methods if you're not interested in building a custom solution.

In the spirit of REST, use the following HTTP methods:

  • GET to retrieve data
  • PUT to change data
  • DELETE to clear data

Many operating systems ship with command line tools to send HTTP requests, many scripting languages like Python also have easy support for this.

A popular command line tool for this is called 'curl', we'll use this in the examples below for which we assume that an Illuminator agent has a HTTP server started on port 1024.

Control individual lights

Individual keys can accessed with the following paths:

  • /column/x/row/y (x and y are the column and row numbers)
  • /course/x/key/y (x and y are the course and key numbers)

Use the DELETE method on the paths above to turn a light of.

For instance, using curl to turn a light off on column 1 and row 5:

curl http://localhost:1024/column/1/row/5 -X DELETE

Use the PUT method on the paths about to change the color of a light, the supported colours are: red, orange and green.

For instance, using curl to set the light on column 1 and row 5 to green:

curl http://localhost:1024/column/1/row/5 -X PUT --data green

Control complete maps

Complete maps can be accessed with these paths:

  • /musical
  • /physical

The DELETE method clears an entire map.

For instance, using curl to clear the entire musical map:

curl http://localhost:1024/musical -X DELETE

The GET method retrieves a map.

For instance, using curl to retrieve the physical map:

curl http://localhost:1024/musical -X GET

The PUT method changes all the lights in a particular map.

This supports two formats:

List format

The list format is the same as what can be seen in the 'musical light map' and 'physical light map' ports in Workbench. It's detailed in the beginning of this page. It looks like:

[[[1,2],green],[[1,3],orange],[[2,3],red]]

Bitmap format

The bitmap format has columns or courses as lines and rows or keys as characters in the lines. The letters 'R', 'G' and 'O' are used to indicate the colours of lights as red, green or orange. A space indicates that a light is off.

For instance:

RR GG 
  O  R

Is the same as the following list format:

[[[1,1],red],[[1,2],red],[[1,4],green],[[1,5],green],[[2,3],orange],[[2,6],red]]

For instance, using curl on a bash command line, this can be set in one go like this:

curl http://localhost:1024/physical -X PUT --data $'RR GG \n  O  R'

Using a scripting language like Python, this can be done for example like this:

import httplib
connection = httplib.HTTPConnection('localhost:1024')
connection.request('PUT', '/physical', 'RR GG \n  O  R')