Since I still haven’t managed to figure out I/O, I decided to start by rolling my own square root function. There’s a fairly simple algorithm to do this:

Suppose we want to find the square root of X. We can start by making a guess, we’ll call it G (1 tends to be a good start). We can then square our guess to see if it works out to X, if not, we can get a closer approximation by taking the average of G and G/X. We simply need to repeat this process over and over again until we converge on the square root of X.

To implement this, I wrote two simple functions. First, there was the square root function itself. It looked like this:

sqrt' :: (Floating a, Ord a) => a -> a
sqrt' x
  | x < 0 = error "square root of negative number"
  | otherwise = limit (\g -> (g + x / g) / 2) 1

Basically, the sqrt' function checks the value of its input (x), if it’s negative, it throws an error, otherwise, it calls a limit function that takes a function and a value, and repeats that function over and over until we converge on a constant value. I’ve defined the limit function as follows:

limit :: Eq a => (a -> a) -> a -> a
limit f x
  | thisTry == x = x
  | otherwise = limit f thisTry
  where thisTry = f x

Naturally, I wanted to see how quickly and accurately my function would calculate square roots, so I started out with a number with a known square root… say 4. When I ran the function, this was the instantaneous result:

*Main> sqrt' 4
2.0

Good. That’s what I would expect to see. Let’s see what happens when we try to use the function to calculate the square root of 2, comparing it to the built-in square root function.

*Main> sqrt' 2
1.414213562373095
*Main> sqrt 2
1.4142135623730951

Excellent. So we’ve now established that the function will quickly calculate square roots. Next, I wanted to try doing a little stress testing. I happen to know (from being bored in math class back in my high school days) that if you take a large nubmer and repeatedly take the square root, you’ll eventually converge on the number 1. Let’s try it with a really large number… say 10¹⁰. Putting my newly created limit function to the test, I got the following result immediately:

*Main> limit (\x -> sqrt' x) (10^10)
1.0

That’s impressive, I was expecting it to take at least a second or so to calculate, after all, 10¹⁰ is a pretty large number. It should have to loop around quite a few times before it converges on 1. Let’s try a googol (10¹⁰⁰):

*Main> limit (\x -> sqrt' x) (10^100)
1.0

Still, instantaneous? Challenge accepted. How big do we need to go before we crash the system, or at least slow it down?

As it turns out, pretty big. I got as high as 10⁴⁰⁰ before I managed to hang the machine (while still not consuming more than 2% of my total system memory). That’s pretty impressive. My previous attempt 10³⁰⁰ was still instantaneous.

The one thing I know for sure is that the next time I need to write a program that runs some serious computations, I’ll definitely be considering Haskell.

This post is mainly about my observations on how I’d do things differently if I were to run one again (and I probably will) as well as some reference notes for the people who attended.

What is Cryptography?

For those unfamiliar with cryptography, Khan Academy has an excellent series of video tutorials on the subject, although, they deal mainly with the basic mathematics behind the subject, which I find fascinating, but may not be your cup of tea.

How the Workshop Worked

The workshop was focused on the basics of the GNU Privacy Guard (often referred to as GnuPG or just GPG), which is a free implementation of the OpenPGP protocol, a public key cryptosystem.

The tutorial was broken up into two parts. The first part was a basic rundown on what public key cryptography is, and how to use GnuPG. This part ran pretty smoothly. The second part was the actual key generation and signing. Because of the large number of people present, this ran significantly longer than I had expected; I think I finally went home around 11PM.

How I’d Do It Better

Ideally, when you run a keysigning party, you want people to have their keys generated beforehand. Since this was a tutorial as well, this can’t really be done for some people, but it doesn’t take that long to generate keys.

I think next time, I’ll create some sort of script that will allow people to generate and print a sheet of paper, which can be cut into slips, containing their name, e-mail address, key ID, and fingerprint. Rather than signing the keys at the event, they can simply hand these slips out to the other participants (showing ID where necessary). Afterwards, people can just go home and sign the keys there using the slips to validate them. That way, only the people who are not familiar with the software will need to stay behind for help, and even then, they’ll probably get it after signing a key or two.

Using GnuPG through the Command Line

I was going to write an explanation of how to do the most common tasks in GnuPG, but I found this handy guide to using GnuPG on the command line so I won’t bother duplicating that effort.

Those who’ve been following the evolution of this library, will probably be familiar with the SwitchInput class. It was intended (among other things) to provide functions that would only be called when a physical switch was closed or opened. The EventHandler class is similar, except that the conditions upon which the event is triggered are configurable and the function isn’t limited to running a single loop when the event occurs. I actually considered re-writing the SwitchInput class to be more like this, but given that it might break programs that people had written with it, I opted not to. Perhaps I’ll create a replacement in the future. Like SwitchInput, EventHandler is drived from the Thread class, with the loop() function overwritten. In its place are two protected virtual functions: condition() and on_event().

The condition() Function:

This is the function that is used to determine when the event is to be triggered. Basically, while the EventHandler object is idle, this function will be called every time the object is invoked by a ThreadList object. If it returns true, the event will be triggered, but if it returns false, the handler will remain in an idle state (this is one of those cases where I wish C++ supported lambdas (but that may be the LISP programming I’ve been doing talking (it’s hard to tell, really))).

The on_event() Function:

Once the event has been triggered, instead of calling the condition() function, the on_event() function will be called in its place. This can be thought of as a conditional loop() function. The difference being that when it returns false the handler will return to an idle state and wait for the condition() function to return true again rather than destroying itself.

A Note about kill_flag:

With a regular Thread object, the loop() function is expected to watch the kill_flag value. When it is set to true, the loop() function is is expected to terminate gracefully. As a help, this functionality is already built into the EventHandler::loop() function. If the handler is in an idle state, it will automatically terminate itself on its next call, however it may be advisable to have the on_event() function watch for this value so that it can facilitate a graceful termination (although, this is not strictly required as the handler will be terminated when the function returns false).

While I don’t feel I’ve done anything particularly ground-breaking with this new release, I hope I’ve created an adequate framework for other Arduino developers who don’t want to re-invent the wheel. As usual, I’ve made all the code and documentation available for this version.

Happy Hacking!

Pouring muriatic acid into the etchant (add the peroxide first)

The design printed onto magazine paper (for toner transfer)

Loaded into the heat press

Using the press to transfer the toner onto the board

Cooling the board down before removing the paper

Paper carefully removed from the board to keep the toner intact

The other side

Freshly made etchant starts to turn green as it absorbs copper from the board

Starting to etch the copper off the board

The front of the (almost) finished board

The reverse side of the (almost) finished board

As can be seen from the last picture, I left the board in the etchant a little too long (it was more active than I expected). Apparently, after a few uses it becomes a little slower acting, although I’ve considered using this effect to somehow watermark my boards.

The first decision that had to be made was what PCB layout software to use. Eagle seems to be a rather popular package for PCB layout (for both hobbyists and professionals) and I’ve used it at work, but it’s proprietary. As a free software developer, I’d much rather use a free (as in speech) tool if at all possible, so I set out to find one. Enter gEDA. gEDA is a GPL-licensed suite of PCB design tools.

One of the things that I’ve heard people complaining about when designing Arduino shields is the non-standard pin spacing. I didn’t really get what they were complaining about until I set out to make one of my own. There are four headers (two with six pins and two with eight) on the board, and for the most part they’re pretty standard: 100mil spacing between pins on each header and a 200mil spacing between pins on the gap between the bottom two connectors, but a 160mil gap between the two headers on the top. In the PCB editor, you could just use a 100mil grid if it weren’t for that one header. It really was a bit of a headache to get the pads in the right places.

Not wanting to have to do the work of getting the pins set up properly twice, I decided to make a custom symbol and footprint for an Arduino Uno board. That way, on future Arduino shields, I could simply drop a block representing the Arduino into the schematic and it would automatically place all the pins on the PCB where they’ll fit the board. If I drag one header around, the othes will follow to maintain proper spacing. Quite handy.

Being a suite of programs rather than a single monolithic program, creating PCBs with gEDA is a little more involved than it is with Eagle, but it’s still pretty straight-forward. You start by creating one or more schematics (one per page) with gschem. The schematic files are in a well-documented plain-text format, so you could make them with a simple text editor, but that’s way too hardcore for even me. With gschem, it’s all drag and drop.

The next step is to use the gsch2pcb program to convert your schematics into a pcb file and a netlist (it also creates a .cmd file, but I don’t know what that’s for). From there, you open the pcb file with their pcb layout editor (creatively named pcb) place the components, import the netlist, and then you can use the auto-routing feature to draw all the traces on the board. I had to play with trace and via sizing so that I could get all the traces to fit into two layers. Don showed me a way to manufacture PCBs, but it only works for two-layer boards.

Unfortunately, there are now a number of vias on the board that have a hole size of 20mil… that’s going to require a steady hand to drill. Perhaps in a later version, I’ll use SMT components to free up some space on the board so I can use larger vias.

That’s about it for my progress so far. I’ll be sure to blog some more as I actually attempt to manufacture these boards. They’re going to be a little more complex than I’d like for a first attempt at using this manufacturing process, but I’m always up for a challenge.

Happy Hacking.

EDIT 5 Mar 2011:
I almost forgot to post links to the actual project.

• Here’s my list of custom symbols.
• Here’s my list of custom footprints.
• And last but not least, here’s the actual shield.

Also, there’s a more descriptive tutorial on how to use gEDA on their website.

Wiring Switches to the Arduino

The simplest and easiest way to connect a switch is to just wire a dry contact switch directly from the input pin to the ground pin taking advantage of the Arduino’s internal 20k pull up resistor. That way, when the switch is open, the input will read HIGH, and when it’s closed, the input will read LOW (although, this is a little counter-intuitive for most people).

NOTE: Pull-up resistors usually don’t work well for pin 13 because of the built-in LED (see below).

The next way is to supply your own pull-up resistor by wiring the switch the same way, but also running a resistor between the 5V power output pin and the input pin. I’m not sure why anyone would choose this option over the former, but you could if you really wanted to. The logic for reading this switch would be the same as in the previous case.

The last way is to supply a pull-down resistor. In this case, you hook your dry contact from input to the 5V supply, and your resistor from the input to the ground pin. In this case, the logic makes more sense, where a LOW input level is an open switch and a HIGH input level is a closed switch. This option works well with pin 13.

What SwitchInput Provides

Primarily, SwitchInput is intended to provide a layer of abstraction for a switch. Instead of thinking of a switch input in terms of HIGH and LOW logic levels, it allows you to think of the switch in terms of open and closed states, which is a little easier on the brain. The SwitchInput class has is_open() and is_closed() member functions that will return true when the switch is open or closed respectively (and false otherwise… obviously).

That’s hardly the best feature of the SwitchInput class however. Another handy feature of this class are the on_open() and on_close() functions. These are virtual member functions that are automatically called when the state of the switch changes, and can be overridden to perform tasks in an interrupt-like manner when these events occur.

As their names would imply, the on_open() function is called when the state of the switch transitions from closed to open, and the on_close() function is called when the switch changes from from open to closed.

That brings us to our third feature: automatic debounce filtering. This helps to clean up “dirty” input signals. With most switches, when you close or open them, they don’t transition cleanly from one state to another; the voltage tends to “jitter” back and forth. Without some kind of filtering, this would cause on_open() and on_close() to be called repeatedly for no reason, which needless to say, would be undesirable.

This feature operates transparently. When the voltage level of the input changes, the object will wait for a pre-determined number of milliseconds (50 by default) before doing anything. If at the end of this time period, the level is different from what it was at the beginning, the appropriate function (on_open() or on_close()) will be called. Otherwise, the input change will be treated as a spike and be ignored.

A Note about SwitchInput

This class is derived from the Thread class since it needs to do logic in the background for the debouncing and edge-detection. As such, it must be added to a ThreadList object (such as main_thread_list) just as any other Thread object would. Don’t expect your switch to work if you forget to do this.

Source and Documentation

As always, the most recent version of the source is available under the GNU General Public Licence on GitHub, and the documentation is available on my web site.

Happy Hacking.

EDIT 2010-11-11:
As of version 0.4, the SwitchInput class now has time_open() and time_closed() member functions which will return the time for which the switch has been open or closed (in milliseconds).

It started when I was looking at the code that defines the switches (SoonCon2010Badge.h) and saw this:

#define SWITCH_0  0
#define SWITCH_1  1
#define SWITCH_2 35
#define SWITCH_4  7

Yes, that’s right, the switches are numbered 0, 1, 2 and 4. A little odd, but I decided that I should investigate farther.

I wrote a test program that would check the statuses of these switches and blink the red segment of the LED on the top differently depending on which switch was depressed. I remembered hearing that the switches had internal pull-up resistors, so their normal (open) state would be high.

I set up the blinking patterns like so:

What I’ve discovered from playing with this is that the switch on the bottom left is SWITCH_1 and the switch on the bottom right is SWITCH_4. I’m assuming that the switch on the top right is SWITCH_2, but according to my program, it is continuously depressed, and SWITCH_0 (I’m assuming this to be the reset pin) is never depressed.

I suspect that this is a problem with my board rather than a problem with my code.

If there’s anyone else out there who’s been able to compile and install new firmware onto their badge, can they do me the favour of trying my code out and describing the blinking patterns they see?

The code is on github (the switch-test branch). It can be found here.

Update 2010-10-17:

This issue has been resolved. I found a patch on the original sourceforge page that I have imported into the git repository.

Anatomy of a Typical Arduino Program

In order to understand what this library does, it is important to first understand what a typical Arduino program looks like.

A typical Arduino program has two main functions. First there is a setup() function that is called once when the system is powered on. This is typically used for initializing variables, setting pins as input or output, starting up serial communication, etc. Once the setup() function completes, there is then a loop() function that just gets called again and again and again and again… until the system loses power or breaks down.

So What Does this Library Do Differently?

First of all, a program that uses this library has no main loop() function (well, it does, but it’s part of the library; it doesn’t have to be separately written).

Instead, the library provides a Thread class. This class can be derived from to provide the basic functionality for a single thread. Each Thread has its own loop() function which works in basically the same way as the loop() function we all know and love. The only major difference is that the loop() function in a Thread returns a boolean value (true if the loop needs to be called again or false if it doesn’t). When the Thread completes, it will automatically destroy itself freeing the memory it occupied to be used for other things.

ThreadList Objects

Once a Thread object is created, it then has to be added to a ThreadList object (through the add_thread() function). One of these is already created by the library. It’s called main_thread_list and it’s run in place of the main loop() function.

What a ThreadList does is call the loop() function from the first Thread in the list, then it calls the loop() function from the next one, and so on and so forth. Once they’ve all been called, it returns to the first Thread and starts over again. Whenever a Thread has completed its run, it is automatically removed from the ThreadList.

Tiered ThreadLists

An interesting thing about ThreadLists is that they are Threads in and of themselves. That way a tiered system can be crated where a lower-priority ThreadList object can be placed inside of a higher one. That way, the higher-priority ThreadList will call one loop() from each of the high-priority Threads, and then a loop() from the first Thread in the lower-priority list. It will then call the loop() function in all of the high-priority Threads again, and then the next one from the low-priority list… and so on.

The kill() Function

Rather than waiting for it to run its course, a Thread can be killed by calling its kill() function. There are two levels of “kill” that this function offers. The first (recommended) way is much more polite. It simply sets an internal variable called kill_flag to true telling the Thread that it should start finishing up. Its loop() function is expected to check for this and behave accordingly.

The second way of killing a Thread is to call kill(true). This will essentially kill the Thread outright without any warning. Do not use the delete keyword on a Thread! This will cause memory corruption.

Limitations

One of the major potential problems with this library is the fact that a single Thread that gets hung will lock the entire system up, since the next Thread can’t be called until the current one finishes its loop() function.

For this reason, it is unwise to use blocking functions such as delay(), because they will cause a delay in all the other threads as well. To help get around this, the Thread class has three functions that will not allow the loop() function for that Thread to be called again until a specified amount of time has passed. These functions are sleep(), sleep_milli() and sleep_micro(); which suspend the Thread for a set number of seconds, milliseconds and microseconds respectively.

The Thread class also provides pause() and resume() functions. As the names imply, the pause() function will suspend the Thread until the its resume() function is called. Obviously, the resume() function would have to be called by another (non-suspended) Thread, so care should be taken with these functions.

Where Can I Get It?

The library is available for download under the terms of version 3 the GNU General Public License on github here. The full documentation for the library can be read here.

Hopefully, this will be useful to someone other than me.

Happy Hacking.

EDIT:
I almost forgot to mention that this library also requires another simple library called newdel to enable the new and delete keywords. It’s available (public domain) here.

EDIT 2010-10-09:
Moved the project to github and updated the links.

EDIT 2012-07-01:
This library is now available under the Lesser General Public License (verion 3 or later).

After some discussion in the comments of my last entry, I decided that my next attempt should be to add a check after every move to make sure that I hadn’t boxed any positions in, making them unreachable.

I almost dismissed this idea because I originally thought that it would involve checking every position on the board after every move, but it’s only necessary to check the eight positions that can be moved to from the current one.

The end result was this: on a 7×7 board, I can now compute the same path in 614 iterations as opposed to the 4430 required before. This represents an efficiency increase of slightly better than 720% (although that admittedly doesn’t account for the overhead added to each iteration by the check itself). An 8×8 board still takes an unknown amount of time however.

The thing that this check doesn’t take into account is the fact that there could be a cluster of positions that can reach each other, but can’t be reached from outside; as opposed to a single, isolated position. I had thought of this before I implemented the check, but hoped that it wouldn’t be a significant problem. It now seems that it may be.

It would seem that the next step is to find a way to look for clusters of isolated positions, although I haven’t yet quite decided how to go about that from a programming standpoint. Whatever I do, I’ll have to make sure that the checking process itself is as efficient as possible.

More details as I make more progress. As usual, here’s the source and documentation.

EDIT – 13 Feb 2011:
The source and documentation for this version were lost. I was able to recover the source (without doxygen comments) from Google’s cache, but I had to re-write much of the documentation. The code is now hosted at GitHub.

If we increase the size of the board to 6×6, we don’t even use up 1% of the possible permutations and the result is still calculated in an imperceptibly small amount of time.

By the time we increase to 7×7, we’re still using less than 1% (I’m assuming much less) of the possible permutations, but the result takes a few fractions of a second to calculate.

At 8×8 it gets really interesting. The gauge still doesn’t register (as expected) but I let the program run for about a minute or so with no result.

This would seem to indicate that as the size of the board increases, the percentage of permutations that we need to exhaust decreases (I’m assuming exponentially) but the amount of time needed increases (also exponentially… which I kind of expected).

From this we can extrapolate that at a size of 10×10, I will probably die before the program reaches a conclusion. If there’s a better way of calculating this it’ll either involve a radical optimization of the existing program or (more likely) writing a new one from scratch.

Once again, here’s my code and documentation.

As a matter of interest, I left the original program running in the background. We’re currently sitting at 18+ hours with (surprise) still no result.

EDIT – 13 Feb 2011:
The source code and documentation were lost. I found the source cached on Google (it’s now hosted at GitHub) and regenerated the documentation.