hello world

The tradition of learning a new system by writing a “hello world” program reached the wider public in 1978 in the book The C Programming Language by Brian Kernighan and Dennis Ritchie:

This is the the basic hurdle; to leap over it you have to be able to create the program text somewhere, compile it successfully, load it, run it, and find out where your output went. With these mechanical details mastered, everything else is comparatively easy.

Of course, that was written in the days of shared computers, teletypes and line printers. In these days of embedded systems, rather than outputting the text “hello world”, the program might turn on an LED. On Rascal you can do both. Here’s how:

hello world

Browse to your Rascal’s home page

http://rascalNN.local/

where NN is the serial number of your Rascal. You should see the Rascal’s home page. Change the browser address to:

http://rascalNN.local/editor/

Click the add page icon, enter the name “hello.html”, then click Create.

In the file list, click templates, then click hello.html. In the editing pane, change the section “rascalcontent” to:

Click the Save button, then click the file name “templates/hello.html” at the top of the editing pane. This completes Kernighan’s exercise.

hello world

Rascal hello world page

Flashing the LED

To flash the LED, first add a button. Click the browser back button to go back to the editor, open templates, click hello.html and update “rascalcontent”:

Save and test as above. There is now a red button which interacts nicely with the mouse but doesn’t yet do anything when you click it. Go back to editor, open hello.html and change the script section below “rascalcontent” to:


Save and test. Clicking the button should now open a dialogue box saying “Click!”.
If it doesn’t, make sure you saved your changes, then check the punctuation in the script section, especially the parentheses, curly braces and semicolons. If it did, congratulations – you have just written some JavaScript!

The strange looking line starting with a dollar sign is a jQuery statement. Rascal includes the jQuery library whose motto is “write less, do more”. Here we are using it to capture the button click and do something.

Before we can make the button flash the Rascal’s LED, we need to dive into Rascal’s engine room. Go back to editor but this time open the file server.py. This is a file of small functions written in Python which can be called from a web page to make things happen. Scroll down to the bottom of server.py just above the line if __name__ == "__main__": and insert the following code:

@public.route('/flash_led', methods=['POST'])
def flash_led():
    import pytronics
    if pytronics.read_pin('LED') == '1':
        pytronics.set_pin_low('LED')
        message = "LED off"
    else:
        pytronics.set_pin_high('LED')
        message = "LED on"
    return (message)

Python is quite fussy about indentation so if you haven’t used it before, it might be best to copy and paste this code. This function tests whether the LED is already on (the value of the pin is 1) and if so turns it off (set_pin_low), otherwise it turns it on. It also returns a message saying whether the LED is off or on which we can ignore for now.

After editing server.py, you need to do two things – click the Save button and then click Reload pytronics. The latter restarts the Rascal web server so that it uses the new version of server.py.

Finally, we need to change hello.html to call the new Python function but before doing that, check that the current version is still working. Click hello.html in templates, then click its name at the top of the editing window. Does clicking the button still display an alert? This isn’t a complete test but it does demonstrate that your change to server.py appears not to have stopped things working. We can now add a call to the new server function. Change the script section to the following:

Save and test. Clicking the button should turn the Rascal’s second LED on and off (this is the LED at the opposite end of the Rascal board to the Ethernet connector).

To make the button flash the LED, we added another jQuery statement $.post() which sends a request to server.py. This completes the embedded systems version of “hello world”.

Extra Credit: Display the LED status on the screen

jQuery $.post() expects to receive a reply. That’s why the flash_led function in server.py returns a message which we are currently ignoring. We can retrieve the message by adding a “callback function” to the jQuery post statement:

Save this change and make sure that the alert message is correct.

It would be even better to display the message next to the button. To do this we have to add somewhere for the message to go. Add a line to “rascalcontent”:

As before, save and test. Incremental testing makes it easier to find mistakes! Finally, replace the alert in the jQuery post callback function:

This new jQuery statement replaces the text in the <span> tag with the post response.

The finished Rascal hello world page

Setting up a Mac as a Rascal development system

Updated October 2012 for the Rascal Beriberi release

I’ve been using the Mac for the past few weeks to put together some new pages for Rascal and it works well. Here’s how I set it up:

You first need a copy of your Rascal directory /var/www. There are a number of ways you can upload this but initially I used scp. In Terminal, starting from your home directory, make a directory called rascal-dev and copy everything into it:

$ mkdir rascal-dev
$ scp -r root@rascalNN.local:/var/www/ rascal-dev/
...
$ cd rascal-dev

When finished, cd into rascal-dev as shown above. You now need to install the Rascal web framework Flask. There is some good advice on the Flask site where the recommended first step is to install virtualenv. On OS X this requires install_name_tool which is part of Apple’s Xcode developer tools so you need to install these first. With Snow Leopard, after registering as a developer (free), you can login and download Xcode 3.2.6 from the Apple developer site. With Lion the Xcode 4.2.1 installer is available free from the App Store (remember to install it after it has downloaded). You can now install virtualenv and use it to set up a virtual python environment:

$ sudo easy_install virtualenv
...
$ virtualenv env
New python executable in env/bin/python
Installing setuptools............done.
Installing pip...............done.

Within this environment, anything else you install will only affect this environment. First you activate the environment:

localhost:rascal-dev davids$ . env/bin/activate
(env)localhost:rascal-dev davids$

(note that the shell prompt has changed) and then install Flask:

(env)localhost:rascal-dev davids$ pip install Flask

This installs Flask, the Jinja2 template system and the Werkzeug toolkit.

However, before you can run the Rascal web server, you will need to comment out
the imports of uswgidecorators and pytronics at the start of the file public/server.py:

from flask import Flask, render_template, request
# from uwsgidecorators import *
# import pytronics
import os, time

The final step is to start your development Rascal web server:

(env)localhost:rascal-dev davids$ python debug_public.py
* Running on http://0.0.0.0:5000/
* Restarting with reloader

If you now open a browser and go to http://localhost:5000/ you should see your Rascal home page.

From now on, whenever you want to do some Rascal development on your Mac, you just open Terminal and type these three lines:

$ cd rascal-dev
$ . env/bin/activate
$ python debug_public.py

Rascal Home Page

Running the Rascal Editor
You can also run the Rascal editor on the Mac. Before doing so, you will need to make it possible for the editor to find the files in the public folder. On Rascal the public folder is at /var/www/. On the Mac there is no directory /var/www/ so an easy solution is to create a symbolic link www in the /var/ directory which points to the rascal-dev folder:

localhost:var davids$ sudo ln -s /Users/davids/rascal-dev/ www

The next step is to install the Flask Login extension:

(env)localhost:rascal-dev davids$ pip install Flask-Login

Finally, you will need to provide a password file to allow you to log in. If you have a Rascal, you can copy its password file from /etc/passwd to the rascal-dev directory. This will allow you to log in to the development editor using the same password as on the Rascal. You need to tell the Rascal editor where to find the password file. Edit the file editor/__init__.py, commenting out the old location and adding the new one:

# PASSWD_FILE = '/etc/passwd'
PASSWD_FILE = '/var/www/passwd'

Alternatively, if your Rascal hasn’t arrived yet, you can edit the file editor/__init__.py and comment out all of the @login_required lines.

Now you can start the editor from another terminal session on port 5001 as follows:

$ cd rascal-dev
$ . env/bin/activate
$ python debug_editor.py

At this point you have the public web server running on port on 5000 and the editor on port 5001. Connect to the editor as follows:

http://localhost:5001/editor/

The last step is to make the editor aware that the public server is running on port 5000. Edit the file rascal-dev/editor/static/js/editor-resize.js and set the value of DEBUG_ON_MAC to true:

// Debug and resize constants
var DEBUG_ON_MAC = true;

After making this change and reloading the editor, you will be able to create and edit files, view pictures in the editor and open templates by clicking the file name in the location bar above the edit pane.

Mac OS X Lion and Creating a new Rascal ext3 microSD card

Using this technique it is possible to insert the Rascal ext3 microSD card in the Mac card reader and have it appear on the Mac desktop. According to the README for FUSE-EXT2 it is possible to write to the card but the document states “Although write support is available (and it is pretty stable) please do not mount your filesystems with write support unless you do not have anything to lose”. In any case, as far as I know, it is not possible for Mac OS X to format an SD card as ext3 so I chose not to take the risk.

I have VMWare Fusion installed so it was relatively easy to create a virtual machine running Ubuntu 10.04. Make sure you install VMWare Tools which optimises connectivity between Mac OS X Lion and the virtual machine. Once Ubuntu is running and assuming you have already installed OSXFUSE and FUSE-EXT2, you can do the following:

  1. Insert the Rascal microSD card into the Mac card reader. The “rascal-beta” card should appear on the Mac desktop
  2. In VMWare Fusion choose the Virtual Machine menu, then in the submenu USB & Bluetooth choose “Connect rascal-beta (Apple Internal Memory Card Reader)”. The “rascal-beta” card should disappear from the Mac desktop and in a few moments appear on the Ubuntu desktop
  3. In Ubuntu 10.04 it will have been mounted as /media/rascal-beta. You can then follow Brandon’s recipe for archiving the existing card filesystem.
  4. Having made a copy, you can right-click the mounted SD card in Ubuntu and choose Safely Remove Card. The card will disappear from the Ubuntu desktop but the card reader is still connected to the Ubuntu VM. Then from VMWare Fusion: Virtual Machine: USB & Bluetooth choose “Disconnect rascal-beta (Apple Internal Memory Card Reader)” and the SD card should reappear on the Mac desktop.

I repeated this with a new card, formatting it as ext3 according to Brandon’s recipe and then extracting the saved archive onto it. I’m running my Rascal off this copy.

While repeating these steps before writing this post, after ejecting the card safely from Ubuntu it entered the dreaded state on the Mac “The disk you inserted was not readable by this computer.” with the options Ignore and Eject. I tried everything – multiple restarts of the Mac and Ubuntu, uninstalling and reinstalling FUSE-EXT2 and OSX-FUSE etc. After an hour I concluded that the card must have been corrupted and was about to wipe it in Apple Disk Utility when I noticed it was read only. I had accidentally locked the card when pulling it out of the reader.

Apart from this, the above procedure seems reasonably robust. I did try some experiments without installing OSXFUSE and FUSE-EXT2 on the Mac. If you choose Ignore in the initial card insertion dialogue, it is possible to connect the card reader to the Ubuntu virtual machine and get it to recognise the card. However this seems to be a matter of luck and often requires multiple restarts.

First posted in the Rascal hardware and software forum.

Mac OS X Lion and Backing up the Rascal ext3 microSD card

I hadn’t had much experience with Linux so when my Rascal arrived, I thought I ought to back up its microSD card. I inserted the card into my iMac and got the message “The disk you inserted was not readable by this computer.” with the options Initialize (No…!), Ignore or Eject. What to do? Googling for “Mac OS X and ext3” mostly returned old links. There was a something called MacFUSE but development stopped before Lion was released. To cut a long story short, there does seem to be a recipe that works well – you insert the Rascal microSD card into the reader and it appears on the Mac desktop, just as it should.

The Recipe
Before starting, it is worth reading this recent blog entry which provides an overview.

  1. Install OSXFUSE (FUSE for Mac OS X), a replacement version of MacFUSE that does work with Lion and is being maintained. IMPORTANT In the initial installation dialogue you must tick “MacFUSE Compatibility Layer”. According to the developer, installing it afterwards won’t work! OSXFUSE v2.3.8 can be downloaded from here
  2. Install FUSE-EXT2 which runs on top of MacFUSE to provide support for ext2 and ext3 filesystems. You can read about it here and download from here.

It is probably a good idea to restart your Mac after the installation.

After this, when you insert the Rascal microSD card, it should appear on the desktop. You can then back the card up by following Brandon’s recipe for archiving a file system. Note that the location of the card will be /Volumes/rascal-beta/.

The SD card has to be unlocked to allow it to be mounted. However this recipe always mounts the filesystem as read only.

First posted in the Rascal hardware and software forum.

Mac OS X Lion, Rascal and nano

When using Terminal on OS X Lion to connect to the Rascal (e.g. ssh root@rascalNN.local), I noticed that nano was unreliable. For example when deleting a long line, the cursor sometimes jumps to the right leaving characters on the screen which do not match the nano buffer (which you can redisplay with Ctrl-L). This seems to be a common problem with Lion, not confined to Rascal, for example see this blog page. The problem seems to be that Lion has changed the default TERM setting from xterm-color to xterm256-color.

There are a number of ways to change your TERM setting but one of the simplest is to open Preferences from the Terminal menu, choose the Settings tab, click on the scheme you will be using (e.g. “Basic”) then click on the Advanced tab and change “Declare terminal as:” from xterm256-color to xterm-color. This setting gets carried over to Rascal when you use ssh and seems to make nano work as expected. If not, according to a nano FAQ, setting TERM to vt100 should always work!

First posted in the Rascal hardware and software forum.

In the beginning

I stumbled across The Rascal on 15 Dec in the entries to 2011 Best Open Source Project at Postscapes, a site which tracks the Internet of Things.

I was intrigued by Rascal designer Brandon Stafford’s explanation that he had built it because “I want to connect weird stuff to the internet”. Many of his points rang true with me, particularly the disconnect between hardware and software. For example, you discover a neat embedded board but getting anything useful to run on it has an extremely steep (possibly unsurmountable) learning curve. All I wanted was to control the heating of a remote property over the internet and all I could find were closed, proprietary solutions. I’d bought one which didn’t work properly and there was nothing I could do about it.

Rascal is different. I watched the getting started video and was convinced. I’d noticed that a few beta Rascals had gone on sale in November and emailed Brandon to ask if there were any left. Happily there were.

By the next day (16 Dec) the first international Rascal was on its way from Somerville MA and on 30 Dec it landed safely in Oxford UK.

Postscript

  • I plugged it in and “it just worked” as the video promised.
  • Rascal won the Postscapes Editor’s Choice award for Best Open Source Project. There’s an interview with Brandon Stafford here.
  • I was lucky – the Rascal store is now sold out (but more are on the way).