Generating and Using Barcode Line Courses

Overview

The Pocket Bot can read and decode "barcode"-like line courses that contain data. Fundamentally, each page contains 1 byte (8 bits) of information, with 2 bits used for timing calibration. This leaves 6 bits of information that can be encoded per page, meaning that a page can encode any value between 0 and 63 (26 = 64). These values can be used for anything you want: commands, numbers, or even lower-level instructions (such as conditionals or loops, if you are so inclined).

Generating these courses by hand would be too tedious, so we've written a command-line (CLI) tool to do it for us. It is called course-encoder and the source code is available here.

Compiling and Running

The course-encoder tool is a small program written in C and it needs to be compiled first. Fortunately, this is easy if you are already familiar with gcc and make.

Download and cd into the course-encoder directory and run:

make

This will generate the course-encoder binary. To use it, specify the base filename of the output images followed by the n values you want to encode (between 0 and 63).

./course-encoder <base filename> <value 0> ... <value n-1>

For example, if you want to generate a course with the values 0, 10, 42, and 63, you would write:

./course-encoder mycourse 0 10 42 63

and the program would generate 4 image files containing those encoded values.

Printing a Barcode Course

With your barcode images generated, you'll now need to print them out. This needs to be done with care since most printers, by default, will print images with a sizeable margin on each side of the page, which we don't want. Ideally, the barcode images should occupy the entirety of each page when printed, and the Pocket Bot Barcode program expects this.

When printing your course, be sure to configure your printing/page setup such that the margins on the side of the page are as small as possible, or even zero. This is possible in most image-viewing programs (such as Microsoft Paint). We recommend printing out just a single page first to verify that you've done this correctly, and then print the remaining pages with the same settings. Another possibility is to import the images into a word-processing program (such as Microsoft Word) and sizing each image to fill an entire page, but that obviously requires slightly more work compared to simply printing the images directly with the correct printer margin settings.

Assembling a Barcode Course

By now, you've printed a barcode course. Most home printers can print the barcode courses with a very minimal margin, but that will still need to be trimmed. Using scissors or a utility knife, carefully trim off the top and the bottom blank margins of each printed barcode page so that they can be joined together seamlessly with no gaps between them. Make sure not to cut off the informational footer, though.

Each page is automatically labelled with the page number, encoded value, and intended direction of the Pocket Bot. Lay each page down in the correct orientation and tape them together at the corners so that there is no visible seam in the line course. We also recommend taping the course corners down onto a floor or desk surface (or foam core board) for extra stability.

Here is an example of a completed barcode course:

And now you're ready to run the barcode course! See the instructions on the demo programs for more details.

Built-In Course Commands

The Pocket Bot comes pre-flashed with the Barcode program (among others) that includes support for a variety of commands, represented by the following encoded values:

  • 0: NOP (do nothing)
  • 10: Flash red LEDs
  • 11: Flash green LEDs
  • 12: Flash blue LEDs
  • 20: Wiggle
  • 21: Shake back and forth
  • 42: Spin with rainbow effect
  • 63: EOF (end of instructions)

Using any of these values with the provided Barcode program will result in those instructions being executed.

Writing Custom Commands and Instructions

Of course, you're not limited to only those commands shown above! If you wish, you can write your own commands, values, or entirely different instructions by modifying the barcode.c source file in the provided Pocket Bot source code, available here. Note that you'll require a Midnight Make Programmer if you want to upload your own code to the Pocket Bot.