(there’s usually a big printed dot near the PWR pin for orientation)

There has been some confusion about what PWR is w.r.t. +3V and how to use it, so let me elaborate a bit.

First: “+3V” is the main regulated power reference for most chips and circuits. And to make it more complicated: it’s actually 3.3V, not 3.0V. The “+3V” label merely identifies the pin (VCC would be too confusing).

The ATmega on the JeeNode, as well as most (but not all) chips on attached plugs run on this 3.3V voltage level. It is also the reference level for all digital I/O (0 = 0V, 1 = 3.3V), as well as for the ADC when used for analog inputs (1023 steps of 3.22580645161 millivolt each).

As for the other supply pin: “PWR” is usually a higher voltage from which +3V is derived.

There’s a voltage regulator on the JeeNode which can take any input voltage on “PWR” up to about 13V as input and which produces the 3.3V regulated voltage on the “+3V” pin.

The JeeNode regulator has some limits: it’s can’t supply more than 250 mA and it can’t dissipate more than about 600 mW. It’ll shutdown if either of these are exceeded (and it’ll get damaged if you feed it more than 13V). These figures are fairly limiting: if you run a JeeNode off 12V on the PWR pin, then it actually won’t be able to supply more than 70 mA. With 5V on the PWR pin, the limit will be current, not power dissipation, i.e. 250 mA max.

That’s for a JeeNode with through-hole components, i.e. an MCP1702 regulator in a TO-92 package. With the JeeNode SMD and JeeNode USB, you get even less power from the regulator: at most about 250 mW of heat dissipation. That’s 150 mA @ 5V, and only 28 mA @ 12V. In short: the JN SMD and JN USB are not really meant to be powered from more than 5V – or at least not without an extra external regulator (on the plus side: the MCP1703 supports up to 16V on the PWR pin). Note also that the JeeNode USB doesn’t support more than 7V on the PWR pin, due to limitations of the on-board LiPo charger – but that should not be an issue since it’s really only meant to be powered from 5V via USB.

As you can see, there are several limiting factors as to what voltage is supported on the PWR pin. Keep in mind that JeeNodes were designed for ultra-low power consumption, and the regulator was selected for its extremely low idle current draw, not its “high-end” characteristics.

But that’s not all…

One trap for the unwary is with the JeeNode USB: it doesn’t actually feed 5V to the PWR pin when connected to USB but only 4.2V. This is due to the LiPo charger circuit, which allows a LiPo battery to be connected between PWR and GND. With a LiPo battery, the JeeNode USB becomes a very convenient stand-alone unit: low-power untethered operation while not connected to USB, and automatic LiPo charging while connected to USB. It even has a voltage divider on board to monitor the LiPo battery voltage (tied to PC6, i.e. analog 6 in Arduino-speak).

The trouble here is that when you connect plugs to the JeeNode USB, you won’t get the full 5V you might expect. This affects all those plugs which don’t run entirely off +3V but expect some higher voltage on PWR.

And here’s another tricky situation…

With the AA Power Board, you can run JeeNodes off a single AA cell. In this case, there isn’t a voltage higher than 3.3V anywhere in the circuit – so what to do with the PWR line? Well, there’s a solder jumper on the AA board to let you decide: it’s normally open, but you can connect it to either +3V or to the battery “+” (i.e. 1.2..1.5V). Obviously, this setup will be even less suited for plugs which expect a higher voltage than 3.3V to operate.

As you see, the +3V pin is solidly specified as always being 3.3V, but the PWR pin level can be all over the map.

The following plugs are especially affected:

• the LCD Plug will work, when used with a 3.3V display (as shipped by JeeLabs), but will only be suitable with 5V displays if PWR carries 5V

• the Graphics Board assumes that PWR is 5V, because the display needs it (it’ll probably still work with 4.2V, but PWR should not be above 5V)

Most plugs will be fine, though, since they only use the +3V supply. The only issue here is to make sure that the total current consumption off +3V is not too high.

Using a JeeNode with an unregulated power supply

The maximum allowed voltage on the PWR pin is about 13V. Unfortunately, many 12V power bricks are fairly badly calibrated, and often deliver substantially more than 12V under no-load conditions. You could easily damage the JeeNode’s on-board regulator with a cheap 12V power brick – better use a 5V or 9V brick.

If you do want to power a JeeNode off 12V (perhaps you need 12V on the rest of the circuit for LEDs, relays, or motor power), then the best approach is to insert a 5V regulator and feed that 5V level to PWR. This can easily be done with a “7805″ regulator chip, which is available from many electronics parts sources.

So now, the JNµ can be put to sleep as well. Here’s the jouleTest sketch I used, tweaked to run on the JNµ as well:

And sure enough, about once every 10 seconds it shows that familiar packet-transmit current consumption:

The blue line is the AC-coupled supply voltage, a 3x AA Eneloop battery pack in this case. It supplies about 3.8V, but when running off a 1000 µF cap, it looks like this continues to work down to 1.8V (well below the RFM12B’s minimum 2.2V specs) – although with only about half the transmit power by then.

This current use fingerprint is almost identical to the ATmega328 running this same code. Not surprising really, since it’s the RFM12B which determines most of the power consumption, not the ATmega vs ATtiny difference.

Onwards!

I prefer to use my own programmer’s editor, because it supports multiple programming languages and has a lot more features for software development (such as Git integration, code folding, and save-on-lose-focus). The Arduino IDE supports external editors by disabling its own one – which is an option in the preferences:

Now I can simply use my own editor and switch to the Arduino IDE for compiling and uploading.

One advantage of using an external editor, is that you can look at other source code than just your own sketches. In the rest of this post, I’m going to describe how to look at one of the most interesting parts of the Arduino IDE: its run-time library, i.e. the Wiring code which adds supports for everything which makes an Arduino different from the ATmega’s on which it is based.

Note: what follows is specific for Mac OSX, but apart from the location of these files and the editor used, you should be able to transpose all of this to your own beloved computer environment.

The first task, is to figure out where the Arduino IDE’s run-time code is located. In Mac OSX, this code is located inside the Arduino application. To view this area, you can right-click on the Arduino app:

This leads to the following directory structure:

The interesting bits are inside the “hardware” folder:

Here are the first few lines of “Arduino.h”, for example (this used to be “WProgram.h”):

These source files are where everything specific to the Arduino IDE’s runtime happens. The “Serial” object, and the “millis()” code, for example. If you want to really understand what the Arduino is about, then it’s well worth going through some of these files. As you’ll find out, there’s no magic once you start looking in the right places.

Try it!

It’s going to take a while for all current inventory units to “flush through the system” so to speak (both DIPs and SMDs), but at some point this month all ATmega’s will be running the same boot loader as the Arduino Uno. Faster, smaller, and – hopefully – no more troubles with Windows being unable to upload sketches through FTDI.

One of the things I’ve done is to turn one of the new JeeNode Blocks into a dedicated Portable ISP Programmer for DIP-28′s. It’s the same isp_repair2 sketch as before (modified for the Block’s minor pin allocation diff’s):

Note the 16 MHz resonator behind the ZIF socket. Here’s the wiring:

There’s no 10 kΩ pull-up resistor for RESET, because ATmega’s have a (weak) built-in pull-up.

To avoid the delay-on-hardware-reset, I’ve added a push-button which briefly shorts +3V and GND together through a 10 µF electrolytic cap. Enough to force the JeeNode Block into a hardware reset. There’s a 10 kΩ resistor across the cap to discharge it afterwards. This is really quick because the reset occurs on button press i.s.o. release.

The savings are minimal – just 1..2 seconds more for the standard bootstrap – but for production, it matters. Total flash time, including boot loader, RF12demo sketch, and setting all the fuses is now just a few seconds:

• insert DIP chip
• close ZIF socket
• press button
• wait for two LED blinks
• open ZIP socket
• remove programmed chip
• rinse and repeat…

When a serial port is connected via FTDI, you can see the progress of it all:

Now let’s just hope that this version of OptiBoot doesn’t lead to the same mess as the previous one.

If you have older JeeNodes or other ATmega328 boards running previous bootstrap loaders, I suggest looking at the recent ISP programmer post and the older summary. You might consider bringing all units up to date, because with a mix of boot loaders you end up constantly using the wrong one in the IDE and having to adjust board types each time.

Just be careful when messing with boot loaders. If the process goes wrong and you pick the wrong fuse settings, then you can end up with a “bricked” unit (only a high-voltage programmer can recover from such a state).

But apart from that: enjoy the doubled 115.2 Kbaud upload speed and the 1.5 Kb extra space for sketches!

I made a few small improvements to that sketch:

1. the RFM12B is powered down at the end, so that the unit only consumes a few µA’s once done
2. the programming rate has been improved by getting rid of those horribly slow digitalWrite() calls, etc.
3. updated RF12demo and OptiBoot to the latest version (v8 and v4.4, respectively)

Furthermore, I switched from the funky switches to plain jumpers, with the following layout:

Another change is that the default with no jumpers is now to burn RF12demo w/ OptiBoot for use with a 16 MHz resonator – this is a good default for JeeNodes, JeeNode USB’s, and JeeNode SMD’s. To select the other options, just hook this up to USB, change the jumpers, and watch the serial output report on reset.

This is the output with no jumpers and no target board attached:

This is the output after a normal programming cycle (again, the default case, no jumpers installed):

Programming takes only a few seconds. Note that this programmer is fully self-contained and includes its own LiPo battery, so all you need to do is press the 6 pins on the ISP header pads. The neat thing is that due to the normally-discharged cap on the target board, the brief power dip caused by touching the ISP pads will generate a hardware power-on reset in the programmer, which then immediately starts its programming cycle.

So the the whole workflow is now as follows:

• grab this thing – and let’s call it a “Portable ISP Programmer” (PIP!)
• press the pins against the ISP header of the unit to be re-flashed
• watch the initial LED blink on the programmer as it comes out of reset
• wait 2..3 seconds
• watch the second LED blink, indicating that it has successfully completed programming

There is no power switch, since the programmer enters total power down when done. To re-charge, plug the programmer into a USB port and wait for the “charge” LED to turn off. Note that pressing the reset button also works, but that it adds a small boot loader delay before the isp_repair2 sketch gets started.

This has become so convenient, that I can now take any old JeeNode lying around here, and reset it to a well-known state in just a few seconds, before re-using it for some project or experiment.

The problem was to come up with a robust way to connect to the target board, but I think I’ve found a solution:

Take a 4-pin header, slightly enlarge the holes in the plastic, and then gently-but-forcefully press a couple of Pogo pins in there. I’m using the type with a large head with sharp edges. Here’s the whole assembly:

After that, it’s a matter of attaching all the wires and tying / glueing things together:

These units are all refurbished ones with a defective radio, since that’s not needed here.

The ZIP straps hold the battery and wires in place. The hot glue does the rest:

These programmers are considerably more effective than you might think – tomorrow, I’ll explain why…

A fitting moment to get that Dutchtronix clock working (a lot easier than this geek version):

I bought this little kit long ago, not realizing that a low-end USB scope front-end can’t deal with it. Besides, it turns out that it didn’t work back then because of some bad solder joints (ground planes and 15W soldering irons don’t go well together – even my current soldering iron has trouble heating up some of those pads!).

Anyway, this is as far as the Hameg HMO2024 will go:

Recognizable, but a far cry from what analog scopes can do. That’s what you get when digital sampling, waveform refresh rates, and vector drawing clash (bumping up the sampling rate causes a fuller, but flickering, image).

This design was from 2007, I think – which goes to show that fun stuff (especially clocks) can be time-less!

I wish you a healthy, safe, and happy 2012 – with lots of opportunities to tinker, learn, and create.

Update – for another example of how such X-Y displays differ between analog and high-end vs low-end DSO’s, see this video on Dave Jones’ EEVblog.

It’s time to move on. I’m dropping all support and maintenance of the Ports and RF12 libs, as well as some others. Well, as far as subversion is concerned. All files are kept read-only at svn.jeelabs.org – for reference.

… vive le roi!

But the good news is that all this software has now been moved and updated on GitHub … and is fully supported.

All libraries on GitHub have been adjusted to work with Arduino IDE 1.0 (they may or may not still work on 0022 or 0023, but that will be supported only to the point of accepting patches to increase backward compatibility).

There is one change which I’ve been meaning to get to for a long time: the Ports and RF12 libraries have been combined into a new library called JeeLib. This means that you no longer have to include “Ports.h” and “RF12.h” at the start of your sketches (although those still continue to work). Instead, insert this one line instead:

    #include <JeeLib.h>

All the examples from both libraries have been retained, but make sure that the old Ports and RF12 are gone.

There are three other libraries for the JeeNodes which you may be using: EtherCard, GLCDlib, and RTClib. These too are now on GitHib and have all been adapted for use with Arduino IDE 1.0.

So how does one start using any of these libraries? Ah, glad you asked :)

• go to GitHub, and pick the library you’re interested in to get to its home page
• at the bottom of each home page is a README section with the latest info – always worth a check
• one of the links at the top is marked “ZIP” – you could click it to download everything as ZIP archive
• … but you shouldn’t !

The reason for this is Git. If you download a ZIP archive, unpack it, and install it in the right place (which is in the “libraries” folder where all your sketches are), then you’ll get a copy of the code your after, but no way to stay up to date. That might sound like a minor detail, but with open source, there are usually many changes over time. Bug fixes as well as new features. If you grabbed a ZIP file, then you’ll be forced to re-install the next version over the previous one every time there is an update. This quickly gets very boring, and can lead to all sorts of awful mistakes, such as overwriting a file you had fixed in some way (after a lengthy debug session, long ago).

I can’t stress it enough: don’t grab open source software and install it on your disk by just downloading and unpacking it. Not just the stuff from JeeLabs – any open source software distributed in source code form. It’s a nuisance, a ticking time bomb, a mine field, a disaster waiting to happen – get the message?

There is only one sane / long-term approach to working with source code, and that’s through a Version Control System. In this case Git – in combination with GitHub, which is the web site where all source code is stored.

So instead of downloading a ZIP or TAR archive, you need to create a “clone” of the original code on GitHub. The difference with the ZIP archive is that a clone knows where it came from, and gives you the ability to find out what changed, to instantly update your clone, or to revert to any older version, since GitHub keeps track of all versions of the code – past, present, and future.

The trick is to get started with Git and GitHub without drowning in the capabilities they offer. How depends on the environment you’re in:

• On Windows, you can install TortoiseGit – then you need to get that clone onto your machine. For JeeLib, you’ll probably need to enter this path to it somewhere: git://github.com/jcw/jeelib.git

• On Mac OSX, you need to install the Xcode developer tools, which includes Git (it’s a free install from the App Store). If you have an account at GitHub (or don’t mind getting one, it’s free), then I highly recommend getting the GitHub for Mac application. If not, you can always use the command line, like so:

      cd ~/Documents/Arduino/libraries
      git clone git://github.com/jcw/jeelib.git
  

• On Linux, you need to install git through whatever package manager you’re using. On Debian / Ubuntu, this command line will probably do it:

      sudo apt-get install git-core
  

  After that, it’s the same as the Mac OSX command-line version, i.e. “cd …” and “git clone …” (see above).

So far, this is only a little more involved than grabbing that ZIP file. The gains start when you want to update your copy to the latest version. In git-speak, this is called “pulling” the latest changes (to your local disk). I encourage you to search around on the web, it’s usually as simple as doing “git pull” from inside the cloned area (from the command-line, some GUI, whatever). The difference with re-installing is absolute security – “git pull” will never overwrite or lose any changes you made, if they conflict with the original.

If all you do is track changes from time to time, then this is all you need to benefit from Git and GitHub.

If you actually make changes, then you’ll need to dig a little deeper when a “conflict” occurs, meaning you’ve made a change which interferes with changes made in the original on GitHub. But on the plus side, you’ll also be able to easily submit your changes (GitHub calls this “making a pull request”, i.e. pulling your changes back into the original). Why bother? Because contributions, no matter how small, are what make open source software fly!

Welcome to the world of open source software collaboration – where code lives, evolves, and grows.

This post was prompted by a message on the forum, about what this whole “JeeNode” thing is, really.

Here are a JeeNode v6 and an Arduino Duemilanove, side by side:

Let me start by saying, tongue-in-cheek: it’s all Arduino’s fault!

Because – let’s face it – the core of each Arduino and each JeeNode is really 95% the same: an Atmel AVR ATmega328P chip, surrounded by a teeny little bit of support circuitry and placed on a printed circuit board. So part of the confusion comes from the fact that the Arduino introduced its own conventions, moving it further away from the underlying common ATmega technology.

The differences between an Arduino Duemilanove and a JeeNode v6 – which resemble each other most – are:

• the JeeNode has a “skinnier” shape, incompatible with Arduino “shields”
• the Arduino runs at 5V, whereas the JeeNode runs at 3.3V (this carries through to all I/O pins)
• the JeeNode includes a wireless radio module, called the RFM12B by HopeRF
• the Arduino includes an FTDI <-> USB interface, while the JeeNode relies on an external one

There are many other differences, of course – so let’s continue this list a bit:

• the Arduino’s “eco-system” is far, far bigger than the JeeNode’s (translation: everyone who finds out about JeeNodes probably already knows about the Arduino platform, and usually already has one or more of ‘em)
• this carries through to articles, websites, books, and discussion forums – Arduino is everywhere
• you can do lots of stuff with an Arduino without ever touching a soldering iron, whereas the JeeNode is really not usable without some soldering (even if just to solder on a few pin headers)
• different pinouts… it’s one big conspiracy to confuse everyone, of course! (just kidding: see below)

My reasons for coming up with the JeeNode have been documented in the past on this weblog, and can be summarized as: 1) running at 3.3V for lower power consumption and to better match modern sensors and chips, and 2) supporting a simpler form of expandability through the use of “plugs” – little boards which can be mixed and matched in many different combinations.

On the software side, JeeNodes remain fully compatible with the Arduino IDE, a convenient software environment for Windows, Mac, and Linux to develop “sketches” and upload them to the board(s).

The biggest stumbling block seems to be the way pins are identified. There are 4 conventions, all different:

• Atmel’s hardware documentation talks about pins on its internal hardware ports, in a logical manner: so for example, there is a port “D” with 8 I/O pins numbered 0..7 – the sixth one would be called PD5.
• Then there is the pin on the chip, this depends on which chip and which package is being referred to. On the 28-pin DIP package used for an ATmega328P, that same PD5 pin would be identified as pin 11. That’s the 11th pin, counting from the left side of the chip with pin 1 at the top.
• The Arduino run-time library has software to control these pins. For a digital output pin, you can set it to “1″ for example, by writing digitalWrite(5,1). This resembles PD5, but it fails for other pins (PB0 is “8″ in Arduino-land, and PC1 is “1″ if used as an analog input, or “15″ if used otherwise – go figure…).
• The JeeNode organizes several pins as part of 6-pin “Ports” (no relation to Atmels terminology!), each of them having 1 digital and 1 analog-or-digital pin.

The thing about JeeNode Ports is that there are 4 of them, and they can all be used for plugs in the same way. To support this, there’s a Ports library which lets you define port objects. This is an abstraction layer on top of the Arduino runtime. The reason is that it lets you associate a port object with a header on the JeeNode:

    Port myport (2);

Then you can connect your hardware / sensor / plug / whatever to the header marked “P2″ on the JeeNode, and access it as follows:

    myport.digiWrite(1);

This happens to be the same pin as in the examples above, i.e. PD5 of an ATmega, pin 11 of the 28-pin DIP chip, and digitalWrite(5,1) on an Arduino. This also means that there are numerous ways to perform the same action of setting pin 11 of the chip to a logical “1″ (i.e. 3.3V or 5V):

• the “raw” C-level access, using Atmel’s register conventions and definitions (fastest, by far):

      PORTD |= 1 << 5;  // or ...
      PORTD |= _BV(5);  // same thing
      bitSet(PORTD, 5); // same thing, using an Arduino macro
  

• the Arduino way of doing things:

      digitalWrite(5, 1);
  

• the JeeNode Ports library way of doing things, as shown above:

      Port myport (2);
      myport.digiWrite(1);
  

• … let’s throw in an extra bullet item, since every other list in this post appears to come in fours ;)

The one (minor) benefit you get from using the Ports approach on a JeeNode, is that if you attach your hardware to a different port, say port 3, then you only need to change a single line of code (to “Port myport (3);” in this case). The rest of the code, i.e. everywhere where its pins are being read or written, can then remain the same.

For an overview of all pinout differences, see also this weblog post. For full details, see the JeeNode PDF docs.

In the world of ultra-low power, the weakest link in the chain will determine whether your sketch runs days, weeks, months, or years… low power can be a surprisingly elusive goal. The last microoulombs are the hardest!

But it’s actually quite easy to get some real savings with only a little effort. Here are some things to avoid:

• Don’t optimize in the wrong place – it’s tempting to start coding in a way which seems like a good idea in terms of power consumption, although more often than not the actual gains will be disappointing.

• Don’t leave the lights on – the ATmega is amazingly easy to power down, which instantly reduces its consumption by several orders of magnitude. Make sure you do the same for every major power consumer.

• Don’t just sit there, waiting – the worst thing you can do in terms of power consumption is wait. Unfortunately, that’s precisely what the Arduino runtime’s delay() and delayMicroseconds() calls do.

Ok, with this out of the way, I’ll describe a very simple way to get power consumption down – and hence battery lifetimes up (waaay up in fact, usually).

The trick is to use a convenience function from JeeLib (a.k.a. the Ports library). It’s in the “Sleepy” class, and it’s called loseSomeTime(). So if you have this in your code:

    delay(100);

… then you should replace it with this:

    Sleepy::loseSomeTime(100);

You also need to include the following code at the top of your sketch to avoid compilation and run-time errors:

    #include <JeeLib.h>

    ISR(WDT_vect) { Sleepy::watchdogEvent(); }

As the name indicates, the timing is not exact. That’s because the ATmega is put into a power down mode, and then later gets woken up by the watchdog timer (this is hardware, part of the ATmega). This timer can be several percent off, and although the milliseconds timer will automatically be adjusted by loseSomeTime(), it won’t be as accurate as when updated by the crystal or the ceramic resonator often used as system clock.

The second issue with the watchdog is that it can only delay in multiples of ≈ 16 ms. Any call to loseSomeTime() with an argument less than 16 will cause it to return immediately.

Furthermore, loseSomeTime() can only work with argument values up to 60,000 (60 seconds). If you need longer delays, you can simply create a loop, i.e. to wait 120 minutes in ultra-low power mode, use this:

    for (byte i = 0; i < 120; ++i)
      Sleepy::loseSomeTime(60000);

One last aspect of loseSomeTime() to be aware of, is that it will abort if an interrupt occurs. This doesn’t normally happen, since the ATmega is shut down, and with it most interrupt sources. But not all – so if loseSomeTime() returns prematurely, it will return 0. Normally, it returns 1.

The trade-off of loseSomeTime() is power consumption (system clock and timers are shut down) versus accuracy.

But the gains can be huge. Even this simple LED blink demo will use about 10 mA less (the ATmega’s power consumption while running at 16 MHz) than a version based on delay() calls:

    void loop () {
      digitalWrite(4, 1);
      Sleepy::loseSomeTime(250);
      digitalWrite(4, 0);
      Sleepy::loseSomeTime(250);
    }

To reduce this even further, you could shorten the blink ON time as follows:

    void loop () {
      digitalWrite(4, 1);
      Sleepy::loseSomeTime(50);
      digitalWrite(4, 0);
      Sleepy::loseSomeTime(450);
    }

The LED may be somewhat dimmer, but the battery will last 10x longer vs. the original delay() version.

Battery-powered operation isn’t hard, you just have to think a bit more about where the energy is going!