You need an Arduino connected to a PC with a working Arduino IDE. These directions are for Arduino IDE version 0018, but they work for the earlier 0017 version too.

Since Bitlash is an Arduino library you upload with a sketch, you need to be comfortable uploading sketches. Get this working first to save debugging headaches. There is plenty of help over at the Arduino Forums.

The current version of Bitlash is available at the Download page.

The Arduino Development Environment Guide specifies this procedure for installing third party libraries:

"To install these third-party libraries, create a directory
called libraries within your sketchbook directory. Then unzip
the library there."

There is also a post on the Arduino weblog with further explanation.

So, to install Bitlash,

• Create a directory called libraries within your sketchbook directory

• Unzip the download and copy or move the Bitlash distribution folder into the libraries folder you just created Rename the resulting folder to simply bitlash, if necessary, to remove the version number. You should end up with a folder setup that looks like this:

• Restart the Arduino IDE; if all goes well, you will find the bitlash library listed in the Sketch / Import Library menu.

• Select File / Examples / bitlash / bitlashdemo to open the demo sketch, then File / Upload to compile and upload it to your Arduino.

When your upload is complete, you are ready to connect to Bitlash. Proceed to the next section on Connecting.

Connect to the serial port at 57600 baud using whatever terminal emulator works for you. Here are some options:

• You can use the built-in Arduino Serial Monitor, but see the note below
• On Windows, HyperTerminal seems popular
• On OS X I use screen, CoolTerm, and bitty.py
• On Linux screen is available on most distributions

You can use the Arduino “Serial Monitor” function with Bitlash, but you must employ a bit of a workaround to compensate for the fact that Serial Monitor does have a way to send a line ending carriage return at the end of a line of input.

The workaround is that you must end each line of input with the 'accent grave' character, the '`' found at the top left of many keyboards. This workaround is not necessary if you use a terminal program that sends the line ending characters.

Here is an example using the screen program in OS X to connect with Bitlash on a USB-connected Arduino. The /dev/tty.usb… part is the virtual serial port name that you can find in the Arduino Tools/Serial Port menu and the 57600 is the baud rate:

$ screen /dev/tty.usbserial-A7003pQ3 57600
bitlash 1.1 here! (c) 2010 Bill Roy -type HELP- 335 bytes free
> 

Congratulations, you are up and running: Bitlash is listening for commands, as signified by the '>' prompt.

Now that you have a command prompt you can type a command, and press Enter.

Here is the usual Hello World example you might run as your first Bitlash program:

> print "Hello, world!"
Hello, world!
>

While you're there you might check the arithmetic:

> print 2+2
4

No discussion of “Hello, world!” for embedded systems would be complete without blinking an LED. This example shows how to build a complete Bitlash application using macros and auto-start.

First it is necessary to introduce the concept of pin variables: Bitlash gives direct access to the digital IO pins via single-bit variables named d0, d1, d2, and so on. You can read a pin variable's value and print it like this:

> print d12
0

…and assign it like this:

> d13=1   // turn on pin 13

…though you must remember to set the pin mode if you want the port to be an output:

> pinmode(13,1)

So, returning to blink13, what we want is to toggle the pin periodically. Let's define a macro named toggle13 to toggle the pin:

> toggle13 := "d13 = !d13"

A macro named toggle13 containing the Bitlash code “d13=!d13” is defined and saved in EEPROM. When the macro toggle13 runs, this program text sets pin d13 to the logical complement of its current value: if it was zero, it becomes one, and vice versa.

Now all we need is to arrange for toggle13 to be run at the desired toggle rate, let's say every 1000 milliseconds; and let's not forget to set pin 13 as an output. By using the special macro name startup we designate this macro to be automagically run at boot time, completing our application:

startup := "pinmode(13,1); run toggle13,1000"

List our macros to make sure they're right using the ls command:

> ls
toggle13:="d13 = !d13"
startup:="pinmode(13,1); run toggle13,1000"
>

You can run the startup macro from the command line to test:

> startup
(the LED on pin d13 is blinking)

You can also restart to test the power-on startup:

> boot
bitlash here! v1.0...
(the LED on pin d13 is blinking)

Congratulations! If you get this far, you have a free-standing development environment on your Arduino.

You will very likely find it useful to proceed to the Documentation Index.

Happy Hacking!