In this guide, we're going to write a quick program that makes the LED wired to pin #13 on an Arduino blink once every second. Let's get to it, shall we?

Writing the Shard

First off, navigate to the shards folder in a fresh Alicorn installation and open up the hello.js file using your favorite text editor (I suggest Atom) if you don't have a favorite yet). By default, the contents of the file should look something like the below:


alicorn.shard("hello")
    .create(function(self) {
        console.log("Hello, Alicorn! Open spheres/hello.js to get started!");
    })

    .update(function(self) {

    })

    .destroy(function(self) {

    });

Let's go ahead and break it down; if you're not familiar with Javascript syntax, you can probably make it through this tutorial in one piece - but I'd suggest taking a peek at some other online tutorials if you're confused.

The first line, alicorn.shard("hello"), declares a new Shard named hello. This is what makes this JS file a valid Alicorn Shard instead of just another stray script.

After that, we have the only function callback that does something in this Shard, .create(function(self) { ... }). Alicorn will automatically call this function when the Shard is first created, executing any commands contained within. If you come from an object-oriented background, you can think of this as the constructor for the Shard. In this case, the function simply prints a single message directly to the Alicorn console.

Finally, there's two empty functions: .update(function(self) { ... }) and .destroy(function(self) { ... });. These are called when the Shard is updated (about a thousand times per second) and destroyed, respectively. You'll notice that we chain the callbsck functions together by simply omitting a ; after create and update and prepending a . to all three.

Now, we're going to add some things to the script and, more specifically, the create callback, to allow us to connect to an Arduino and toggle its state:

  • An arduino variable that represents the physical Arduino.

  • A state variable to keep track of the current state of the Arduino's LED.

Go ahead and add the arduino and state variables to the top of the script and replace the content of the create callback with arduino = self.require("Arduino"). By the time you're done, our Shard should be similar to the following:


var arduino;
var state = false;

alicorn.shard("hello")
    .create(function(self) {
        arduino = self.require("arduino");
    })

    .update(function(self) {

    })

    .destroy(function(self) {

    });

The require("arduino") function on the self variable asks Alicorn to attempt to find a Shard by the name of "Arduino" and retrieve an instance of it for the current Shard (denoted by self). Since we don't specify a port to connect to (by passing a second argument to require(...) containing the port name), it will find the first Arduino connected to the Alicorn server and return a reference to it.

With an Arduino connected, we now need to actually do something with it. To do this, we'll want to add the code below to our update callback:


.update(function(self) {
    self.sleep(500);

    arduino.setDigitalOut(13, (state = !state));
})

The above code will be executed every time Alicorn broadcasts an update (roughly one thousand times per second), and will do the following:

  • Put the Shard to sleep for half a second (500 milliseconds) via a call to self.sleep(500), allowing other Shards to do things while this one waits to toggle the LED.

  • Once the Shard wakes up, it'll toggle the state of the LED via state = !state.

  • Finally, it will set the the state of pin #13 (the LED) on the Arduino via a call to the arduino.setdigitalOut(13, state) method.

Once you're completely done, the hello.js file should look something like this:


var arduino;
var state = false;

alicorn.shard("Hello")
    .create(function(self) {
        // Gets a reference to the IO for an Arduino.
        arduino = self.require("Arduino");
    })

    .update(function(self) {
        // Go to sleep for half a second.
        self.sleep(500);

        // Toggle our state variable and set the
        // Arduino's pin #13 to equal our new state.
        arduino.setDigitalOut(13, (state = !state));
    })

    .destroy(function(self) {

    });

Using the Shard

All you have to do now is connect an Arduino to your computer and configure it to work with Alicorn:

  1. Plug the Arduino into your computer, usually with a USB cable.

  2. Navigate to the shards/firmware/ArduinoUno folder within your Alicorn folder and open up the ArduinoUno.ino file with the Arduino IDE. If you do not have the Arduino IDE, you can download and install it from the Arduino website.

  3. With the IDE open, hit the compile and upload button.

With that tedium out of the way, go ahead and launch your Alicorn server! If all goes well, your Shard will be registered, created and begin blinking the LED on any Arduino running Alicorn firmware that's connected to your computer!

From here, you might consider taking a look at the Leapmotion and Arduino example for a quick guide on adding an element of control to your blinky Arduino.