Changes in the Arduino 1.0 release: How to migrate

Splash screen for the Arduino 1.0 IDE.At long last, the Arduino team has released Arduino 1.0 – an update to the development environment and core libraries that make the Arduino hardware do its thang.  The 1.0 update has been in the works for a while, and covers a lot of changes, including some you’ll notice and some you won’t.  How does all this affect your Arduino projects?  Read on to find out.

This article doesn’t attempt to cover everything that’s different in the new release, just the things that will likely affect your existing code and your current workflow. Think of it as a migration guide. For information on all the major changes, check out the Arduino team’s official blog post or the release notes.  You can also download the Arduino 1.0 release here.

Major changes: the Arduino 1.0 IDE

Arduino 1.0 IDE graphical changes.

One of the first things you’ll notice is that the IDE looks different, with a new color scheme and updated icons for compilation and upload.  Menu items have been changed in some cases, error messages have been updated, and there are a few new board types reflecting recent hardware releases (including the new ADK and Ethernet boards, which are mighty awesome additions if we do say so ourselves).  You also get a progress bar when compiling or uploading, which is handy when you’re twiddling your thumbs and wondering if that massive sketch is ever going to finish transferring.

Major changes: the Arduino 1.0 core libraries

Overall, porting existing code to use the new IDE and libraries should be straightforward.  However, there are a few changes you’ll want to look out for, particularly if you’re using the contributed libraries that come packaged with the core code.  With the release of Arduino 1.0, the team stated that they were working to future-proof the code base, but they did so at the expense of 100% backwards-compatibility.  Here’s a summary of the changes and what you can do to get your code working with the new platform:

First, print() and println() now behave differently, as does any class derived from them (Serial, Ethernet, Wire, etc).

Printing bytes

print(byte) will now print the digits of the byte value as ASCII characters, rather than printing the byte directly.  This is more consistent with how it handles other numeric data types.  In order to send a single byte, use the write() class instead.

Serial.print(byteValue)

should become

Serial.write(value)

Also, print() no longer supports the BYTE keyword, so you’ll want to make the same change anywhere you previously used it:

Serial.print(value, BYTE)

becomes

Serial.write(value)

Write methods in Print-derived classes

If you have a class of your own that’s derived from Print, you’ll need to modify it’s write method. Write now returns size_t instead of void, where the return value is the number of characters written. Make sure to change any mentions of void write to size_t write and handle the return appropriately.

In addition, be aware that Serial transmissions now occur asynchronously. This doesn’t necessarily require you to change any code, but there are situations you might want to. Anything using Serial.print() or similar now is stored in a buffer that is transmitted in the background, allowing your serial communications to be completely non-blocking. This is great news! Previously, you could use the serial buffer to deal with incoming transmissions asynchronously, but now you can also send data and continue on to other tasks immediately, without waiting for the transmission to complete.

Changes to the Wire library

The Wire library also relies on the Stream class, and has been changed to be more consistent with similar classes. Instead of

Wire.send() and Wire.receive()

you’ll need to use

Wire.write() and Wire.read(), respectively.

Also, the write method now requires you to supply a type for any constant arguments. For example, if you previously used

myWire.write(0x20)

you’ll now have to supply

myWire.write((byte)0x20)

The Ethernet library

A few things have been changed in the Ethernet library to make the code cleaner and to follow established conventions from other Arduino sources.

First, the client and server classes add an “Ethernet” prefix to avoid conflicts with other networking libraries. Also, you’ll need to initialize your client class first, then add connection parameters using the connect() method. For example, change

Client client(server, 80);
if(client.connect())

to

EthernetClient client;
if(client.connect(server, 80)>0)

Note that we’re testing client.connect() for values greater than zero because the method returns negative numbers to specify certain errors.

The server class has similar changes, with

Server server(80);

replaced with

EthernetServer server(80);

Finally, just like the rest, the UDP class adds a prefix to become EthernetUDP.

Using older Arduino libraries

If you’re using libraries that haven’t been updated to the 1.0 release, you’ll have to make some slight modifications to make them compatible. Libraries used to require a number of header file includes from the Arduino coure source code. Those includes have now been consolidated into a single Arduino.h header file.

You can simply take the old library and replace all of these headers:

#include "wiring.h"
#include "WProgram.h"
#include "WConstants.h"
#include "pins_arduino.h"

to

#include "Arduino.h"

However, if you want to maintain backwards compatibility, you’ll have to get a bit fancier. Using preprocessor conditionals, we can check the ARDUINO version constant to see whether we’re using Arduino 1.0 or not. If so, we replace the original header files with the new one; otherwise, we leave them alone. Here’s the code to do that:

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

Other interesting additions

Arduino 1.0 includes a few handy changes that don’t require you to modify your code, but might provide opportunities to be more efficient:

Mikal Hart’s SoftwareSerial is now a standard included library, which improves mightily on the old software serial functionality.

Serial and other classes that inherit from Stream now include new parsing functions for incoming data, originally from Michael Margolis’s TextFinder library. They include:

    find(char *target);
    findUntil(char *target,char *term);
    parseInt();
    parseFloat();
    readBytes(buffer,length);
    readBytesUntil(term,buffer,length);

It’s also much easier to store strings to flash memory – just wrap any double-quoted string in F() to save precious RAM. For example: F("Hi Mom!");

That wraps up the major items for now. Do you have any issues you’ve run into when upgrading to Arduino 1.0? Let us know in the comments.

You can also check out our recommendations for the Best Arduino Books to find more resources.  We’ve mentioned which books in that guide are updated for the new release, and we’ll continue to update our descriptions as other authors make the switch.

3 thoughts on “Changes in the Arduino 1.0 release: How to migrate

    • Hi Liudr,

      Thanks for the comment, you’re correct.

      One note about your blog post: the NewSoftSerial library is now the default SoftwareSerial library included in Arduino 1.0. No need to go to Mikal’s website anymore because it’s packaged with the core installation. Anyone who was using it can upgrade and simply change the relevant #include statement (though he actually renamed the latest version “SoftwareSerial” in preparation for the release).

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>