Arduino 1.0 , Is it the Arduino Team's "Vista"?

This is basically an open letter to the Arduino team:

While it is nice to have an "official" release of the Arduino s/w. The official 1.0 Arduino release
comes with a very high price as it has changed several things in a non backward compatible way.
While the changes to pre 1.0 code are typically minimal to get it to compile/function on 1.0,
the changes are usually beyond the expertise of the intended target audience of the Arduino.
You have to look no further than all the recent posts going on in several of the forums asking
about all the "strange" errors they are seeing when building their code on 1.0 and why
their sketches suddenly no longer work or no longer fit in their AVR after upgrading to 1.0

What is somewhat sad is that the Arduino platform had become fairly stable over the past few years
and the number of 3rd party libraries and 3rd party hardware devices that use custom libraries
floating around on the Internet is quite numerous.
The 1.0 release breaks 100% of those existing libraries and some of the existing projects that use those libraries
will fail to function correctly even when the libraries or sketches are updated to compile with the 1.0 release.

In recent years, the pre 1.0 code had essentially become a long term running beta release project which had created a very
stable platform which was very good for the "Arduino" brand and especially good for novices since
the majority things "just worked", including 3rd party libraries and sketches directly out of the box.

1.0 has changed several things in such a way as to be very disruptive and has created instability
in the Arduino platform that is going to last for at least several months if
not much longer as users struggle with trying to get their sketches and 3rd party libraries
up and working.

Contributing to the problem is that the 1.0 release candidates were not very well advertised on the Arduino
Web site. Announcements and links to the release candidates were not put on the main download web page
along side the latest 022/023 releases.
As a result not many users and library developers were actively beating on
it and using it to help discover issues prior to its release.

The end result is that 1.0 is less stable than 0022 or 0023 from a novice user's point of view
because he continually sees that example sketches and libraries he downloads from the internet
or that come with his 3rd party hardware device no longer work with Arduino 1.0

A brief list of some of the issues

  • 100% of all the pre 1.0 libraries will not compile under 1.0
  • certain core header files changed names
  • some function names in certain libraries changed (example: ic2 send() is now write())
  • some functions have the same name but do something different (hardware serial flush() is an example, Print print() is another)
  • flush() on SoftwareSerial() and HardwareSerial() in 1.0 do totally different things.
  • 1.0 generated code is larger and can cause sketches to not fit
    (ethernet code appears to have grown by more than 4k or 80+% in size)
    (SD library is also quite a bit larger)
  • serial code is larger and forces user to use buffered i/o output which changes timing and eats up additional RAM.

It is one thing to add new functionality, it is another to break existing functionality especially
when it is to the level of breaking 100% of the existing code (libraries) from even being able to compile.

Part of the reason that I think the instability will drag out over many months if not longer is that
today, nearly everything will work with pre 1.0 Arduino so there is no immediate need for most users
to upgrade to Arduino 1.0. As time goes by and developers "update" their
code to work with 1.0, some will update their code in ways that no longer work with the pre Arduino 1.0 code.

This can create frustrating situations for the end users that use multiple libraries or code from different
sources in that they may end up in a situation where some of the code only works with pre 1.0 tools and some only works with 1.0 tools.

IMHO, way too much was changed way too late in the game with Arduino 1.0
especially given that some of these non backward compatible changes like the header
file name changes didn't add any additional new functionality.
Also I'm guessing that there will inevitably be additional non backward compatible changes needed
to support the newer non AVR based processors in Arduino that will eventually be worked into
the Arduino tool set.
So I predict that users will not only have to go through the pain of this 1.0 transition
but users are more than likely going to have to go through additional pain again in the near
future as the non AVR based processor support is added into the Arduino toolset.

So that is why I wonder if Arduino 1.0 will be to Arduino what Vista was to Microsoft.
A release that worked fine for some people but many others were not very happy with.

--- Bill Perry


Now since I believe that all criticism should be constructive,
I will offer some suggestions to try to improve the existing situation.

At this point my suggestion would be make using pre 1.0 code much easier use.
And while I know many people would like have a "don't look back" type of mindset
and just tell folks to "get with it" and update their code for 1.0, it really isn't that
simple if you want to continue provide a good user experience especially to less
technical users that may be using libraries and code they find through internet searches.

I believe that the best way to do this is by creating a way to make pre 1.0 code "just work" on the 1.0 release.
Barring re-releasing 1.0 with the pre 1.0 code of say 0023 - which I doubt the Arduino team would ever do,
the best thing would be to put in a "pre 1.0" backward compatibility mode option
in the IDE to help with the transition.
While it wouldn't offer the identical code and sized code as pre 1.0 it would allow
all pre 1.0 code to continue to compile and function under Arduino 1.0
It isn't' that difficult.
My suggestion would be handle to this by offering a "0023 emulation" mode
that sets ARDUINO to 0023 instead of 100.

For dealing with the header file name changes:
You create a new directory:
hardware/arduino/cores/arduino/deprecated
In that directory you create the header files that have changed names
and they are simply stub header files that include the new header files.
hardware/arduino/cores/arduino/deprecated/WProgram.h would include <Arduino.h>
hardware/arduino/cores/arduino/deprecated/wiring.h would include <Arduino.h>
etc..
To enable this deprecated directory to work,
the IDE would add the deprecated directory to the include path when the
"0023 emulation" option was enabled.

For the wire library function name changes:
In the wire library. Add the send() function back in that is a wrapper for write()
with no return status. This will allow older code to continue to use send() with no changes.
This could be handled with or without conditional compilation.

For Print class, add a conditional to revert the print() and write() functions back
to their pre 1.0 functionality and return status.

For HardwareSerial, add a conditional that:

  • reverts the transmit back to no buffering
  • reverts flush() back to pre 1.0 meaning
  • reverts write() back to pre 1.0 void status

For SoftwareSerial
Since flush() didn't exist pre 1.0, this just needs to be fixed.
Fix flush() to work like the 1.0 flush in Hardware Serial.
(waits for the tx buffer to drain vs empty the rx buffer Q)

[ I'm sure that there are others, but there aren't that many in total ]

The overall suggestion is to update the 1.0 IDE, libraries, and core code to include a conditional
(which would be off by default) which can be set in the IDE that can be used to force things work/behave/be named
like the pre 1.0 release.
There are not very many things that need to updated with conditionals and it wouldn't take that long.

I'm guessing that if you consider the amount of time and resources that will be spent tacking down 1.0 transition issues
and explaining these to users and helping them fix their code, I'd bet that it would be less time and effort to
simply update the Arduino libraries, core code and IDE to provide a pre 1.0 mode.
The beauty of having a pre 1.0 mode option available from the IDE, is that this solves the problem for everyone all at once.

--- bill

bperrybap:
The beauty of having a pre 1.0 mode option available from the IDE, is that this solves the problem for everyone all at once.

And the ugly is that it encourages libraries to not work in a post-1.0 world.

Your suggestion actually turns Arduino more into Internet Explorer and less into Vista.

From a support perceptive now users would find that code in 1.0 (current release) didn't work. Code in 1.1 (with compatibility mode) does work. Code in 1.2 (compatibility removed) might not work. Look at the long list of compatibility modes in Internet Explorer and how much effort developers have to go through to support the various versions. This is not a good thing, for anyone.

What is in order is a detailed transition guide: something to help users convert obscure, abandoned code/libraries. Something more than just "Wire.send is now Wire.write."

As far as backward compatibility modes go and their value, I think you need to rethink that one.
There is a simple reason why Microsoft's XP is still so popular: Backwards compatibility.
Businesses and end users all over the world have spent lots of time, effort, and money to get their
favorite applications up and working and many have applications that simply either don't work on the newer OS's
or don't work like they used to.
Backwards compatibility is very important.

I guess my point really was that I see a very rocky road ahead with more non backward
compatible changes being necessary as the non AVR support is rolled in
and the current 1.0 release really doesn't leave behind a stable platform for the AVR users.

It would have been nice to have had at least one stable 1.x "officially released"
platform that users could use while the changes and new feature updates were being bounced around
including adding support for the new non AVR processors.
(0022 was in place for nearly a year and would have made a great 1.0 release)
New capabilities could be done in some other release path where all kinds of non 1.0 backward compatible changes could
be made using the benefit of many years of experience that has come from the current Arduino
development.

BTW,
I was assuming that a "1.1" release would completely and immediately obsolete 1.0 and that any
non 1.x compatible changes could move forward to say a 2.x development tree.
My real preference would call 1.0 a "mulligan". Obliterate it. Make 0023 1.0 and make the current 1.0 a 1.1beta release.

It is a philosophy thing. It is a "don't look back", "you always want the latest stuff I'm giving you" mindset.
I don't subscribe to this mindset.
That type of mindset can be very chaotic for end users and 3rd party developers kind of like what we are seeing today with 1.0
I believe that it is impossible as a developer to ever know or
determine exactly what users need and how they will use things.
Because of that, you must be very flexible and work very hard not to break things especially
things that have been in place for years.

Occasionally, yes it is necessary, but when you do have to break something, you want to do it
in a way that minimizes the pain felt by the install base. That usually means providing an easy
transition path that often means providing some backward compatibility capabilities to give
the user base time to catch up.

Look at the release timing here:
0022 is release 2010-12-24
0023 is released 2011-11-09
1.0 is released 2011-11-30

While I know that 1.0 RC candidates were out for sometime prior to the 1.0 release
the bulk of the Arduino community had no idea about the significance of the changes coming.
It was also very odd that the 0023 release came out after some of the 1.0 candidates.

The 1.0 release took something that was fairly stable, tossed in lots of new things, and made
some changes that broke 100% of the existing install base (for libraries) just before going from essentially
a "beta" to a final release.
That is a very rare thing to do in the software business.
Especially a mere 3 weeks after a previous release.


It would have been nice to have at least one official release before everything was broken.
i.e. make 0023 the 1.0 release and move the current 1.0 release to 1.1beta
That solves everything. People get an official 1.0 release that works with all the install base of code
and those that want to experiment with 1.1beta for the new features can do so but could drop back to 1.0
if there are any issues for them.

--- bill

I agree, updating of the core may have been needed. But a fundamental rule of classes ( the core libraries ) is not to break the interface. You should be able to extend the library interface to support new methods, overload old ones, or change the internal code with out affecting the end users experience. The class object model is designed so people using it do not have to know how it works. By ignoring backwards compatibility and changing the interface everyone has to have knowledge of how the changes affect the class. This may be a key factor in users avoiding the library altogether as they cannot understand the concepts.

Then again, novice programmers may find it just as confusing having multiple overloads of the main functionality.

Either way, if the classes weren't broken they should have been left, as the addition of things like buffered operation over non buffered is just an improvement which could have used a simple run-time or compile-time toggle to enable / disable. Or simply add a whole new class implementing the new method.

'bperrybap' has a good point, the novice user will be encouraged to stay with 0023 until a good portion of user made libraries are fixed to work. This also applies to lazy people like me who cannot actually be bothered changing 25 documents for no particular/noticeable advantage.

And a simple fix for most, why wasn't WProgram.h left in with a single line: #include "Arduino.h", fixing most problems that aren't relying on a library.

I have a fair bit of code now, my source only compiled 2 bytes bigger on 1.0 however, nothing close to 4k.

Anyway, I like to debate stuff just as much as the next person, but I don't see the Arduino team taking a step backwards now.

In Teensyduino I implemented a lot of backwards compatibility. It's really not that difficult, if you care about compatibility. It's not a lot of complex code

Nearly all pre-1.0 code compiles and works as intended when run on 1.0, at least when using a Teensy board (Teensyduino tries to never interfere with Arduino's behavior on Arduino boards). I also back-ported most of the new 1.0 features to 0023 and 0023, again, only when compiling for a Teensy board.

I'd be happy to contribute this code, if the Arduino Team seriously wants it. Or if anyone is interested, you can help yourself. It's all sitting there in the hardware and libraries dirs after running the Teensyduino installer. For example, Wire.h is patched with inline compatibility functions. They're protected by #ifdef so as not to alter anything on Arduino boards. Just delete that #ifdef check, and sketches using the pre-1.0 Wire lib work fine on Arduino boards too.

Of course, the re-purposing of Serial.flush() and change for print(unsigned char) to print as base-10 integers don't seem to have any compatibility solution. But most of this stuff is pretty straightforward... and the solutions already exist.

There is something to be said for changing aspects of a language or library that the authors think could be problematic later on. Java did this quite often, especially in the early days. Yes it caused a little pain, but overall it made Java a better platform because developers were not saddled with the early mistakes of the designers forever.

That said, the Java people didn't simply release an update with changes that broke existing code. They flagged certain interfaces as depricated, and the compiler would emit warnings that this feature would be vanishing in a future release. This gave developers time to make the needed changes. In C/C++, I believe #pragma macros would accomplish this goal.

Now it may not be possible to do this in all cases, especially if method names were changed and then a new method with the old name introduced. With overloading and macros, it could be done. It seems a little late now though. I don't see them recalling 1.0.

I am using a board with a 1284P processor, so I am using cores from avrdevelopers.com. I don't think 1.0 would target my board. The only feature in 1.0 I really want/need is the async write in Serial. I really need to implement that :frowning:

Maybe more like the Arduino Team's Windows NT. All the people who were running W95 don't like the apparently gratuitous incompatibilities and changes, but the technology underneath has a bunch of stuff that is necessary to continue to move forward...

skyjumper:
That said, the Java people didn't simply release an update with changes that broke existing code. They flagged certain interfaces as depricated, and the compiler would emit warnings that this feature would be vanishing in a future release. This gave developers time to make the needed changes. In C/C++, I believe #pragma macros would accomplish this goal.

Now it may not be possible to do this in all cases, especially if method names were changed and then a new method with the old name introduced. With overloading and macros, it could be done. It seems a little late now though. I don't see them recalling 1.0.

Exactly.

And I'm not seriously suggesting they go backwards by actually recalling 1.0
But there are still a few small things that could be done to get many of the old libraries compiling again
to give the install base time to deal with the 1.x changes.
Like adding a WProgram.h and a wiring.h and creating some macros/inline functions for the wire library to name a few.

Basically, I think the 1.0 release should have done the kinds of things that Paul did for his teensyduino
to try to keep from breaking all the existing code going into their first official release.

--- bill

I've tried it but as the sketch i am working on didn't compile and it's not finished i decided to wait until i move over to it. The main thing for me though was not compatibility issues but the colour. I like the 0022 IDE, i like the fact that it is simple and i like the colour. It might not seem like a bit issue but if it's the only window your looking at for hours then it does matter. the new colours for me are too light. (they make my head hurt a bit) The simple thing would be to have a preference setting where you can pick the 3 or so colours that make up the IDE and text (on tabs).
I love Arduino but my heart sank a bit when i saw the colour. It must be really simple to do.

All
I mostly agree with Bill. I would like to add that I don't understand why Arduino sticks to being compatible with a hardware mistake (Arduino Offset Header « Project Blog) and on the other hand creates disruptive software incompatibilities which are 100% avoidable with commonly know -patent free- solutions.
I guess hardware rules in the Arduino core team.
Best regards
Jantje

As you're well aware, software inter-version compatibility is one of the great issues of software development.

For most--if not all--of its development, Arduino 1.0 was billed by the core development team as an opportunity to make backwards incompatible changes compared to the alpha-designated 00xx releases. Certain changes were made to help make the Arduino environment easier for newcomers to learn by fixing some inconsistencies which had developed: e.g. method/function naming.

The past year or so of 1.0 development has been mostly transparent: requests to the community for input, a planning meeting, development coordinated by the public mailing list and multiple beta & RC releases.

A side effect of human nature and the volunteer nature of most library development means there are many libraries which are not currently 1.0-compatible but post-release incompatibility is a great motivator for library authors--some of whom would never update prior to an actual wide-spread release. cough :wink: Patches from users have also been known to speed-up updated library releases.

While an argument can be made for maintaining backward compatibility, when it is known that there will be at least some backward incompatible changes there is another argument that the efforts needed to make things easier for people to stick with older versions is wasted effort. (Particularly when the new version is accompanied by a new file extension.)

The increase in binary size is a concern--although in some cases this will be as a result of increased functionality. At this stage the best contribution is to work out exactly what library/code/functionality is causing the increase and report it as an issue in the project bug tracker.

While painful in the short term, the changes in Arduino 1.0 will hopefully contribute to a stable platform on which to grow until the release of Arduino 2.0 at which time we can complain once again about incompatibility. :slight_smile:

--Philip;

follower:
For most--if not all--of its development, Arduino 1.0 was billed by the core development team as an opportunity to make backwards incompatible changes compared to the alpha-designated 00xx releases. Certain changes were made to help make the Arduino environment easier for newcomers to learn by fixing some inconsistencies which had developed: e.g. method/function naming.

If they took this trail of thought, then they have only done harm to themselves.

Arduino is now being used in schools and other educational institutes. By changing things in such an incompatible manner, most text books and/or tutorials developed by the institutes are now broken, people may out way Arduinos ease of use and decide to use something more stable like PIC's.

And there is just as much arduino info posted elsewhere on the net. Probably more than whats provided at arduino.cc.
As Arduino has no control over these sites, if they are unattended, they will teach people the wrong way to do things.

If provided libraries never get updated, Arduino starts loosing features previously taken for granted by novice programmers.

These things in my opinion could be harmful to an open source project.

The way things look, are we to assume that 1.0 may be ditched because the upcoming 'Arduino Due' can do things more efficiently than 1.0 can provide?

pYro_65:
Arduino is now being used in schools and other educational institutes.

As indeed they have been used ever since they were first created--by the very people who are currently developing Arduino & teaching with them on a daily basis.

By changing things in such an incompatible manner, most text books and/or tutorials developed by the institutes are now broken

A problem with which the teaching members of the development team are familiar. It is in fact part of the reason for the desire to have a stable 1.0 release which teachers & authors can build on in the new (Northern) school year and the future with a degree of stability & certainty. By making multiple incompatible changes at one time resources only need to be updated once.

The release of a non-backwards-compatible 1.0 is the software equivalent of what many people have asked for in terms of the "fix" for the hardware issue of non-regular pin spacing on the I/O connectors. When this has not been done it has been greeted much in the same way as the 1.0 release except for the opposite reason. :slight_smile:

Rest assured the improving of the experience of daily use of Arduino in educational situations has been the driving force behind the development and "fixes" in the release of 1.0--despite many attempts by experienced developers to distract the core team from this goal :smiley:

As Arduino has no control over these sites, if they are unattended, they will teach people the wrong way to do things.

That is indeed one possible negative outcome but is also an unavoidable one if we are to benefit from the organic growth of open source and Free software. Over time the accurate information will float to the top and things will be as they should be, as happened after the incompatible releases between 0015-0020 or so. "We will answer their questions on the forums. We will answer their questions on the mailing list. We will answer their questions in the classroom." We survived then too. :slight_smile: Your assistance in these times are appreciated.

If provided libraries never get updated, Arduino starts loosing features previously taken for granted by novice programmers.

That is also a risk. Given what has happened in the past if a feature is really desired then someone will step up, make the fix, argue with the chorus then release an updated library to the acclaim of thousands*.

*Or one but that's what counts.

Your time on such an endeavour is also likely to be appreciated.

These things in my opinion could be harmful to an open source project.

They can indeed be harmful but my hope is that all of us in the Arduino community will continue to step up to ensure harm is minimised while blinking LEDs and whirring servos are maximised!

The way things look, are we to assume that 1.0 may be ditched because the upcoming 'Arduino Due' can do things more efficiently than 1.0 can provide?

No. While I do not speak for the Arduino development team they were certainly aware of the Due's existence during the development of 1.0 and its stated aim of intended stability.

While your concern for the well-being of the Arduino ecosystem is appreciated I do not yet see Massimo playing his fiddle while the magic smoke rises from a pile of ATmega328s... :slight_smile:

--Philip;

There are some good points in this thread... maybe we should have called Arduino 0022 "1.0" and called the 1.0 "2.0" instead. Also, we could have done a better job of publicizing the 1.0 release candidates. Still, I think there were a lot of people that weren't going to update their libraries or code until the final 1.0 release - and that at some point we just had to go ahead and make the changes we wanted to make. I've seen people start to update their code and libraries already, and think this process will continue as 1.0 becomes more widely used.

Do we have have a list of compatible libraries?

Cheers,
Kari

It might be more useful (and a lot easier) to start compiling a list of INCOMPATABLE libraries...

westfw:
It might be more useful (and a lot easier) to start compiling a list of INCOMPATABLE libraries...

Nah.I have the complete COMPATIBLE list right here.

Arduino.h

There you have it.

Most of the libraries are easy to convert to Arduino 1.0;

find in the library files (ends on .h or .cpp)
#include "WProgram.h"
and change it to
#if defined(ARDUINO) && ARDUINO >= 100
#include "Arduino.h"
#else
#include "WProgram.h"
#endif

and find
#include "wiring.h"
and change that to
#if defined(ARDUINO) && ARDUINO >= 100
#include "Arduino.h"
#else
#include "wiring.h"
#endif

I published the libraries I changed at lemio - libraries (dutch).

I don't know if this is a good step by the Arduino guys, some of the Arduino users are not as technical as others but just like using libraries. Libraries are the hearth of Arduino. And about Vista, if you want a good stable OS choose Ubuntu :smiley: .