We want everyone to be able to develop applications for Holiday by MooresCloud; but we’re still about 12 weeks away from shipping our first units. In order to speed development (both internally and externally) we’ve put together a simulation and development environment which provides a platform that is roughly 99% identical to the code that will be running on the Holiday when it ships.
Holideck is a pure Python simulator for Holiday by MooresCloud, which allows anyone to write apps for the Holiday in two of its three available development environments – HTML5 Web apps using IoTAS, and pure Python.
To install Holideck on your own computer, type the following command into a terminal window (making sure that you’re in the directory where you want holideck installed):
% git clone https://github.com/moorescloud/holideck.git
You should now have a directory named holideck.
If you don’t want to use git, grab the ZIP archive and unzip it wherever you like.
Invocation
% python holideck.py
When holideck launches it opens two ports on the localhost, one for
simulator access, the other presenting the web app interface to Holiday.
The HTML5 simulator simpype will try open port 8888;
if that port is unavailable, it will increment the port number
until it finds a free port.
IoTAS, the Internet of Things Access Server, will
try to open port 80 (which is only possible if python has been
run with root privleges), or if running as a user program, will
try to open port 8080. This port is often occupied by other
applications (Apache, Tomcat, etc), so IoTAS will increment the port
number until it comes to an available port.
All of which is to say that the simulator could be found on port 8888,
but might be at a higher port number, and IoTAS could be found on
port 8080, but could easily be at a higher port number.
The port numbers are given in the output generated by holideck as
it is initializing.
To quit holideck, simply type a Control-C in the terminal window.
Holideck – specifically IoTAS – currently produces voluminous output
for debugging purposes. Eventually, this will be moved to a log.
Using Holideck
Holideck is designed to provide a complete simulation and development
environment for Holiday by MooresCloud. It is implemented in pure
Python.
Holideck is composed of three pieces:
simpype
Simpype is the HTML5-based simulator for the Holiday. Simpype
simulates the 50 individually-addressible 24-bit colour globes
on the Holiday.
To use simpype, point a browser to the simulator’s web page
- generally that will be http://localhost:8888, with the caveats
as given above.
You should see something like this:
What looks like a dashed-line extending from the Holiday image on the left
side of the page is actually the string of globes, with each globe
initialized to black.
The Javascript in the page loaded by simpype will poll the simulator
at approximately ten updates per second, so you do not need to reload
the page to see updates to the simulation.
The simulator can be opened in multiple browsers simultaneously,
with the caveat that each browser will poll the simulator at
10 Hz, so many browser windows pointing to a simulator instance
will produce quite a bit of load on the simulator.
IoTAS
The Internet of Things Access Server, or IoTAS, provides both the
RESTful interface to Holiday by MooresCloud and the web-based
application, control and configuration interface for Holiday.
The interface for IoTAS looks best on a mobile device.
After holideck has been launched, point a mobile device to port
8080 (or possibly higher, with the caveats given above) on the
computer running holideck.
For example, if the computer running holideck is named
iris.local, you should point your mobile browser to
http://iris.local:8080. The home screen
for Holiday’s HTML5 web app interface should then load:
To test holideck, tap on the ‘API demo’ icon, flip the switch, and -
if the demo is working correctly – you should see a random selection
of colors sent to the simulator.
IoTAS defines a detailed RESTful interface to Holiday by MooresCloud.
This will be documented in the holideck wiki.
Holiday web apps
MooresCloud has created a number of demonstration HTML5-based
web apps. These can be used and adapted for your own web apps.
A number of these apps, although included within holideck, are not
yet fully functional and should not be used.
The apps which are functional include:
Colorwheel – Select a colour from the colorwheel, and the entire
string of lights on the simulator will reflect the color change.
API Demo – Generates 50 random colour triplets and sends them
to the simulator.
NRL – Prebuilt color patterns for all 16 teams in Australia’s
National Rugby League.
AFL - Prebuilt color patterns for all 18 teams in Australia’s
Australian Footbal League.
Examples
The examples subdirectory contains two Python applications that illustrate some of the capabilities of Holiday by MooresCloud when connected to a process running either locally on the hardware, or externally on another computer.
Twug-of-War
Twug of War creates an animated Twitter tug-of-war between two competing hashtags.
It’s invoked as follows:
% python tow.py hashtag1 hashtag2
The first time the program is run, it will attempt to authorize itself with
Twitter. A browser window should open, ask for your Twitter credentials if
you’re not logged in (a Twitter account is a prerequisite for Twug-of-War), and,
once logged in, will ask you to authorize the app. Once the app has been
authorized, Twitter will provide a code that must be entered at the terminal
prompt. Once authorized, Twug-of-War will be able to register a stream listener
on Twitter.
The string will initialize to half green, and half blue, with a yellow counter
in the middle of the string. As matching hashtags are seen in the Twitter
‘firehose’, the counter will move one directon or another. When the string is
completely one colour, the program will terminate.
Soundlevel
Soundlevel turns the Holiday by MooresCloud into a real-time sound level
monitor.
It requires some prerequisites to be installed, specifically PortAudio library and the
PyAudio module. Consult the documentation at those websites for more details. (Ubuntu/Debian users can probably install both with sudo apt-get install python-pyaudio, but for OSX and Windows it’s considerably more involved.)
It’s invoked as follows:
% python soundlevel.py
In general the application will correctly detect and use the microphone input
on the computer running Soundlevel, but that may not alway be the case.
Many thanks to Josh Deprez for Soundlevel.
More Caveats
Holideck has been tested on Linux (Ubuntu & Mint), OSX 10.7 & 10.8.
It has not been tested under Windows – and while there is no reason
to presume it will not work perfectly, YMMV. (If you have tested this under Windows, please let us know how it works!)
This is a first release; there are bound to be numerous problems. We
apologize in advance for this.
If you have any serious problems, please leave a message on this thread.
All of this code is released under the MIT License, a copy of which
is included in this repo.