Arduino 1.0 ships on 30 November 2011, after six years of 0.x versions whose numbering said nothing about API stability. It is a release of small but incompatible changes: some sketches written for 0023 no longer compile without edits. It is worth knowing which ones, because anyone keeping libraries and teaching material up to date will have to get their hands dirty.

Context

Up to 0023 the IDE’s development line had never declared a stable API. The environment is written in Java and grew out of Processing; to compile it relies on the avr-gcc toolchain, and to write firmware to the microcontroller through the bootloader it uses avrdude. The user’s sketch, on its own, is not valid C++: a preprocessor adds the #include for the core header, generates the forward declarations for the functions, and produces the .cpp file that then goes to the compiler.

For years this arrangement held, at a price: each 0.x release could change function names, signatures and behaviour with no formal notice. The 1.0 closes that season by fixing a stable point that later sketches can take for granted.

What changes in the sketch format

Two changes affect anyone with existing files straight away.

The extension moves from .pde to .ino. The .pde was shared with Processing, and confusion arose when the two environments found the same files in a folder. The 1.0 IDE still opens .pde, but saves as .ino.

The core header changes name, from WProgram.h to Arduino.h. The change concerns libraries, not sketches: in sketches the preprocessor inserts the right include automatically, while libraries that did an explicit #include "WProgram.h" need fixing. To run the same code on both series you use a conditional compile on the ARDUINO macro:

#if ARDUINO >= 100
  #include "Arduino.h"
#else
  #include "WProgram.h"
#endif

The ARDUINO macro already exists in 0.x (it was 22, then 23 in the last ones); in 1.0 it reads 100. It is the right discriminator for code that must compile on one series and the other.

The breaks in the core API

The change with the widest practical consequences concerns Serial and, more generally, the Stream class, from which Serial, Wire and Ethernet now derive.

write(), print() and println() now return a size_t with the number of bytes written, where they previously returned void (details in the reference below). Subclasses of Stream need adapting, or they stop honouring the interface.

The trickiest break is semantic and gives no compile error: Serial.print(byte) now prints the digits of the number as characters, and to send the raw byte you need Serial.write(). Code that counted on the old behaviour — dropping the value onto the wire as it stands — still compiles but does something else. It is the kind of regression nothing flags until you look at the output on a serial terminal.

In the same vein, the String class has been rewritten (work by Paul Stoffregen, with further changes on top). Some methods that previously returned a new instance — trim(), toUpperCase() — now modify the string in place and return void. Code that assigned the result of s.trim() to another variable needs revisiting.

Stream also gains functions for parsing the incoming stream: find(), findUntil(), parseInt(), parseFloat(), readBytes(), readBytesUntil(). These are additions, not breaks, but they bring into the core things each project used to rewrite by hand.

The standard libraries

The libraries shipped with the IDE follow the same realignment.

Wire (the I2C bus) now derives from Stream: it uses read(), write(), print(), println() like the other streams, instead of the old send()/receive(). SoftwareSerial has been rewritten to handle multiple ports. The Ethernet library adds DHCP and DNS, so a client can take its address from the network instead of having it hard-wired in the sketch. The SD library now keeps several files open at once and can iterate over directories.

For a library maintainer the concrete impact is twofold: update the header include with the conditional compile shown above, and check that any classes deriving from Stream honour the new return signatures.

Critical point

The fragile part of this transition is not 1.0 itself, but the fact that the two series coexist. Anyone writing libraries who wants to serve both those still on 0023 and those who have moved to 1.0 must make the same source compile in both environments, and the tools 2011 makes available are coarse: a version macro and #if. There is no dependency manager, no way to declare “this library requires Arduino >= 1.0”. Installing a library still means copying a folder under libraries/, and the incompatibility surfaces as a compile error on the end user’s sketch, far from whoever wrote it.

For teaching material the problem is the mirror image. Handouts written on the 0.x that show Serial.print(b) to emit a byte now teach something that gives a different result. The example has to be rewritten, not just the version number on the cover.

Implications

Fixing a stable API pays off over time: from here on a sketch can take it as given that digitalWrite(), analogRead(), millis() and the Stream interface will stay as they are, and writing a tutorial, a library or a course costs less when it does not expire at the next release. It is the precondition for a third-party ecosystem to accumulate, rather than having to be rewritten every few months.

The bill is paid once, now, and it is paid by those with 0.x code. Breaking at 1.0 — before the installed base grows too large — is the more reasonable choice: deferring would only have swollen the number of sketches and libraries to convert.

Limits

Some things stay outside the freeze. The library format is not standardised beyond the folder convention: there is no metadata file declaring version and dependencies, so compatibility is checked only by trying to compile. The sketch preprocessor keeps doing implicit transformations — automatic include, forward declarations — that work fine in common cases but confuse when a sketch uses C++ constructs the prototype generator does not handle. And the IDE stays single-sketch: there is no notion of a project with several user-managed compilation units. These are known limits, and 1.0 does not address them: it fixes the API, not the ergonomics of the workflow.

Cover image: An Arduino Uno electronic board with an ATmega microcontroller, USB connector, power jack and rows of pin headers along the edges — photo by Osamu Iwasaki, CC BY-SA 2.0 — https://commons.wikimedia.org/wiki/File:Arduino_UNO.jpg