Posts | Comments

Planet Arduino

Archive for the ‘Hackaday Columns’ Category

I am a crappy software coder when it comes down to it. I didn’t pay attention when everything went object oriented and my roots were always assembly language and Real Time Operating Systems (RTOS) anyways.

So it only natural that I would reach for a true In-Circuit-Emulator (ICE) to finish of my little OBDII bus to speed pulse generator widget. ICE is a hardware device used to debug embedded systems. It communicates with the microcontroller on your board, allowing you to view what is going on by pausing execution and inspecting or changing values in the hardware registers. If you want to be great at embedded development you need to be great at using in-circuit emulation.

Not only do I get to watch my mistakes in near real time, I get to make a video about it also.

Getting Data Out of a Vehicle

I’ve been working on a small board which will plug into my car and give direct access to speed reported on the Controller Area Network (CAN bus).

To back up a bit, my last video post was about my inane desire to make a small assembly that could plug into the OBDII port on my truck and create a series of pulses representing the speed of the vehicle for my GPS to function much more accurately. While there was a wire buried deep in the multiple bundles of wires connected to the vehicle’s Engine Control Module, I have decided for numerous reasons to create my own signal source.

At the heart of my project is the need to convert the OBDII port and the underlying CAN protocol to a simple variable representing the speed, and to then covert that value to a pulse stream where the frequency varied based on speed. The OBDII/CAN Protocol is handled by the STN1110 chip and converted to ASCII, and I am using an ATmega328 like found on a multitude of Arduino’ish boards for the ASCII to pulse conversion. I’m using hardware interrupts to control the signal output for rock-solid, jitter-free timing.

Walk through the process of using an In-Circuit Emulator in the video below, and join me after the break for a few more details on the process.

The Hardware

I revised the board since the last video and removed the support for the various protocols other than CAN, which is the non-obsolete protocol of the bunch. By removing a bunch of parts I was able to change the package style to through-hole which is easier for many home hobbyists, so you can leave the solder-paste in the ‘fridge.

The “Other Connector” on your Arduino

Unlike the Arduino which is ready to talk to your USB port when you take it out of the box, the ATmega chips arrive without any knowledge of how to go and download code, in other words it doesn’t have a boot loader. Consequently I have the In-Circuit-Serial-Programming (ICSP) pins routed to a pin header on my board so that I can program the part directly.

On this connector you’ll find the Reset line, which means with this header I can use a true ICE utilizing the debugWIRE protocol. Since the vast majority of designs that use an AVR chip do not repurpose the reset pin for GPIO, it is a perfect pin to use for ICE. All of the communications during the debug process will take place on the reset pin.

Enter the ICE

When designing a computer from scratch there is always the stage where nothing yet works. Simply put, a microprocessor circuit cannot work until almost every part of the design works; RAM, ROM, and the underlying buses all need to (mostly) work before simple things can be done. As a hardware engineer by trade I would always reach for an ICE to kick off the implementation; only after the Beta release would the ICE start to gather dust in the corner.

In the case of the ATmega, the debugging capabilities are built into the microcontroller itself. This is a much more straightforward implementation than the early days when we had to have a second isolated processor running off-board with its own local RAM/ROM.

One note mentioned in the video is that a standard Arduino’ish board needs to have the filter capacitors removed from the RESET line to allow the high speed data on the line for its debugWIRE usage.

The ICE I am using here is the one made by Atmel, and is compatible with Atmel Studio, there are also other models available such as the AVR Dragon.

ICEyness

The ICE allows us to download and single step our code while being able to observe and overwrite RAM and I/O Registers from the keyboard. We are able to watch the program step by step or look underneath at the actual assembly code generated by the compiler. We can watch variables and locations directly in RAM or watch the C language counterparts. It’s also possible to jump over a sub-routine call in the instance of just wanting to see the result without all of the processing.

It’s worth your time to see even a glimpse of the capabilities of an ICE in action. I recommend that you watch the video where the debugging begin.

Final Words

This video was really about finishing the OBDII circuit so I didn’t really have the time to go over everything an ICE can do, maybe I will do a post dedicated to just the ICE and development environment next time.


Filed under: Arduino Hacks, Hackaday Columns, Microcontrollers, Skills

In a recent post, I talked about using the “Blue Pill” STM32 module with the Arduino IDE. I’m not a big fan of the Arduino IDE, but I will admit it is simple to use which makes it good for simple things.

I’m not a big fan of integrated development environments (IDE), in general. I’ve used plenty of them, especially when they are tightly tied to the tool I’m trying to use at the time. But when I’m not doing anything special, I tend to just write my code in emacs. Thinking about it, I suppose I really don’t mind an IDE if it has tools that actually help me. But if it is just a text editor and launches a few commands, I can do that from emacs or another editor of my choice. The chances that your favorite IDE is going to have as much editing capability and customization as emacs are close to zero. Even if you don’t like emacs, why learn another editor if there isn’t a clear benefit in doing so?

There are ways, of course, to use other tools with the Arduino and other frameworks and I decided to start looking at them. After all, how hard can it be to build Arduino code? If you want to jump straight to the punch line, you can check out the video, below.

Turns Out…

It turns out, the Arduino IDE does a lot more than providing a bare-bones editor and launching a few command line tools. It also manages a very convoluted build process. The build process joins a lot of your files together, adds headers based on what it thinks you are doing, and generally compiles one big file, unless you’ve expressly included .cpp or .c files in your build.

That means just copying your normal Arduino code (I hate to say sketch) doesn’t give you anything you can build with a normal compiler. While there are plenty of makefile-based solutions, there’s also a tool called PlatformIO that purports to be a general-purpose solution for building on lots of embedded platforms, including Arduino.

About PlatformIO

Although PlatformIO claims to be an IDE, it really is a plugin for the open source Atom editor. However, it also has plugins for a lot of other IDEs. Interestingly enough, it even supports emacs. I know not everyone appreciates emacs, so I decided to investigate some of the other options. I’m not talking about VIM, either.

I wound up experimenting with two IDEs: Atom and Microsoft Visual Studio Code. Since PlatformIO has their 2.0 version in preview, I decided to try it. You might be surprised that I’m using Microsoft’s Code tool. Surprisingly, it runs on Linux and supports many things through plugins, including an Arduino module and, of course, PlatformIO. It is even available as source under an MIT license. The two editors actually look a lot alike, as you can see.

PlatformIO supports a staggering number of boards ranging from Arduino to ESP82666 to mBed boards to Raspberry Pi. It also supports different frameworks and IDEs. If you are like me and just like to be at the command line, you can use PlatformIO Core which is command line-driven.

In fact, that’s one of the things you first notice about PlatformIO is that it can’t decide if it is a GUI tool or a command line tool. I suspect some of that is in the IDE choice, too. For example, with Code, you have to run the projection initialization tool in a shell prompt. Granted, you can open a shell inside Code, but it is still a command line. Even on the PlatformIO IDE (actually, Atom), changing the Blue Pill framework from Arduino to mBed requires opening an INI file and changing it. Setting the upload path for an FRDM-KL46 required the same sort of change.

Is it Easy?

Don’t get me wrong. I personally don’t mind editing a file or issuing a command from a prompt. However, it seems like this kind of tool will mostly appeal to someone who does. I like that the command line tools exist. But it does make it seem odd when some changes are done in a GUI and some are done from the command line.

That’s fixable, of course. However, I do have another complaint that I feel bad for voicing because I don’t have a better solution. PlatformIO does too much. In theory, that’s the strength of it. I can write my code and not care how the mBed libraries or written or the Arduino tools munge my source code. I don’t even have to set up a tool chain because PlatformIO downloads everything I need the first time I use it.

When that works it is really great. The problem is when it doesn’t. For example, on the older version of PlatformIO, I had trouble getting the mBed libraries to build for a different target. I dug around and found the issue but it wasn’t easy. Had I built the toolchain and been in control of the process, I would have known better how to troubleshoot.

In the end, too, you will have to troubleshoot. PlatformIO aims at moving targets. Every time the Arduino IDE or the mBed frameworks or anything else changes, there is a good chance it will break something. When it does, you are going to have to work to fix it until the developers fix it for you. If you can do that, it is a cost in time. But I suspect the people who will be most interested in PlatformIO will be least able to fix it when it breaks.

Bottom Line

If you want to experiment with a different way of building programs — and more importantly, a single way to create and build — you should give PlatformIO a spin. When it works, it works well. Here are a few links to get you started:

Bottom line, when it works, it works great. When it doesn’t it is painful. Should you use it? It is handy, there’s no doubt about that. The integration with Code is pretty minimal. The Atom integration — while not perfect — is much more seamless. However, if you learn to use the command line tools, it almost doesn’t matter. Use whatever editor you like, and I do like that. If you do use it, just hope it doesn’t break and maybe have a backup plan if it does.


Filed under: Arduino Hacks, ARM, Hackaday Columns, reviews, Skills

Last Saturday I had a team of teenage hackers over to build Arduino line-following robots from a kit. Everything went well with the mechanical assembly and putting all the wires on the correct pins. The first test was to check that the motors were moving in the proper direction. I’d written an Arduino program to test this. The first boy’s robot worked fine except for swapping one set of motor leads. That was anticipated because you cannot be totally sure ahead of time which way the motors are going to run.

The motor’s on the second robot didn’t turn at all. As I checked the wiring I smelled the dreaded hot electronics smell but I didn’t see any smoke. I quickly pulled the battery jack from the Arduino and – WOW! – the wires were hot. That didn’t bode well. I checked and the batteries were in the right way. A comparison with another pack showed the wires going into the pack were positioned properly. I plugged in another pack but the motors still didn’t run.

I got my multimeter, checked the voltage on the jack, and it was -5.97 V from center connector to the barrel. The other pack read 6.2 V. I had a spare board and pack so swapped those and the robot worked fine. Clearly the reverse polarity had zapped the motor control ICs. After that everyone had a good time running the robots on a course I’d laid out and went home pleased with their robots.

Wires going into pack were correct. Shaved jack showing positive lead on outside of jack.

After they left I used the ohmmeter to check the battery pack and found the wiring was backwards, as you can see in the feature photo. A close inspection showed the wire with a white line, typically indicating positive, indeed went to the positive battery terminal. I shaved the barrel connector down to the wires and the white line wire was connected to the outside of the barrel. FAIL!

This is a particularly bad fail on the part of the battery pack supplier because how hard is it to mess up two wires? You can’t really fault the robot kit vendor because who would expect a battery pack to be bad? The vendor is sending me a new battery pack and board so I’m satisfied. Why did I have an extra board and pack, actually an entire kit? For this exact reason; something was bound to go wrong. Although what I had imagined was for one of the students to break a mechanical part or change wiring and zap something. Instead, we were faced with a self-destructing kit. Prudence paid off.


Filed under: Arduino Hacks, Fail of the Week, Hackaday Columns

Hackaday reader [Jan Ostman] has been making microcontroller-based DIY synthesizers for quite a while now. Recently, he’s opened up the source for a lot of them so that you can play along at home. All of these virtual-analog synths and soundmakers can be realized on an Arduino or AVR ATmega328 if you happen to have one lying around.

Extra parts like a keyboard, some pushbuttons, or some potentiometer knobs to twiddle won’t hurt if you’d like to make something more permanent or more obviously playable, like [Jan] does. On the other hand, if you’d just like to get your feet wet, I’ve tweaked his code to be more immediately plug-and-play. The code is straightforward enough that it’s a good learning platform. So let’s take a quick tour through three drum machines and a string synth, each of which you can build on a breadboard in just a few minutes.

To install on an Arduino UNO, fetch the zip file from this GitHub repository, and move each subfolder to your Arduino sketch directory. You’re ready to play along.

Simple Drum Machines

[Jan] has two sample-playback~based drum machines that he’s published the code for: the dsp-D8 with straight-ahead drum samples and the dsp-L8 loaded with Latin percussion. They’re essentially the same code base, but with different samples, so we’ll treat them together.

Working through [Jan]’s code inspired me to write up a longer article on DDS playback, so if you want to brush up on the fundamentals, you can head over there. The short version is that you can change the pitch of playback of a sample by using a counter that’s much larger than the number of data points you’re going to play.

dds.sch[Jan]’s drum machines all use the AVR’s hardware pulse-width modulation (PWM) peripherals to play the samples back out. You could use something fancier, but this gets the job done with just an optional resistor and capacitor filter on the output, bringing the total parts count to three: Arduino, 1 KOhm resistor, and a decent-sized (0.1 uF?) capacitor. An interrupt service routine (ISR) periodically loads a new sample value into the PWM register, and the AVR’s peripheral hardware takes care of the rest.

One nice touch is the use of a circular buffer that holds the playback sample values until the ISR is ready for them. In the case of the drum machines, there’s not much math for the CPU to do — it just combines the samples from all of the different simultaneous voices — but in his more complicated modules this buffer allows the CPU to occasionally take more time to calculate a sample value than it would otherwise have between updates. It buys [Jan]’s code some breathing room and still allows it to make the sample-playback schedule without glitching.

dsp-l8-shot0001[Jan] adds individual pitch control for each sample, which is great for live playing or tweaking, and you can watch him use them in his two videos: one for the dsp-D8 and another for the dsp-L8. Wiring up so many knobs is a breadboard-salad, though, so I’ve gone through the code for you with a fine-toothed chainsaw, and hacked off [Jan]’s button-and-knob interface and replaced it with the Arduino’s built-in serial I/O.

To play my version of [Jan]’s drum machines, each sample is mapped to a key in the home row: “asdfjkl;”. If you’ve got a proper serial terminal program that transmits each keystroke in real-time, you’ll be tapping out rhythms at 9600 baud in no time. Note that the Arduino IDE’s built-in terminal only sends the keystroke after you hit “enter” — this makes playing in tempo very difficult. (I use screen /dev/ttyACM0 9600 or the terminal that’s built-in with Python’s pyserial library myself. What do Windows folks use for a real-time terminal?)

If you haven’t already, download this zip file, move each sub-folder to your Arduino sketch directory, and connect an amplified speaker either directly to your Arduino’s pin 11 and ground, or include an RC filter. It’ll only take a second before you’re playing. When you want the full version with all the knobs, head on over to [Jan]’s site.

O2 Minipops

[Jan]’s O2 Minipops machine mimics an old-school rhythm box: the Korg mini pops 7. Whether this primitive drum machine is horribly cheesy or divinely kitschy is in the ear of the beholder, but it’s a classic that has been used all over. [Jan]’s named his after an epic album Oxygene by Jean-Michel Jarre. You’ll hear them starting around 1:40 into the clip. Jarre famously used to press multiple buttons on the Minipops, making more complex drum patterns by playing more than one at a time.

The nice thing about having your own Minipops in minipops-shot0001firmware is that you can add the features you want to it. Instead of having to mash down multiple plastic buttons live on stage like poor Mr. Jarre, you can just tweak the firmware to suit. Need longer patterns? You’ve got the RAM. Emphasis? Swing? Tap tempo? It’s all just a matter of a few lines of code.

The sound playback code is just like the simpler drum machines above, so we won’t have to cover that again. The only real addition is the sequencer, but that’s where the real magic lies. After all, what’s a drum machine without some beats? Because there are eight possible drum sounds, each beat is a byte and so four bars of 4/4 time is just sixteen bytes stored in memory. I broke the data out into its own header file O2_data.h, so have a look there for the pre-programmed rhythms, and feel free to modify them to suit your own needs.

In order to make the O2 Minipops immediately playable, I stripped out the potentiometer code again (sorry [Jan]!) and passed off control over the serial port. The “user interface” has five controls. Press j and k to switch between patterns and f and d to speed up or slow down. (They’re under your first two fingers in the home row.) The space bar starts and stops the drum machine.

Try switching between the patterns on the fly with j and k — it’s a surprisingly fun way to create your own, slightly less cheesy, patterns. You need to download this code and give it a try. Trust me.

The Solina

[Jan] has also built up a full-fledged string synthesizer keyboard out of just an Arduino Nano. It’s patterned on the Eminent Solina String Ensemble, and we’ve got to say that it gets the sound spot on.

solina6
Solina — the Original

[Jan]’s Solina is a “virtual analog” in the sense that it builds up sawtooth waveforms in the microcontroller’s RAM and then outputs the corresponding voltage through PWM. And that’s a good start for a string synthesizer, because a filtered sawtooth waveform is a good first stab at the sound put out by a violin, for example.

solina1
Solina — the clone

The secret to the sound of the string section of an orchestra (and to string synthesizers that mimic it) is that it’s a combination of many different bowed instruments all playing at once. No matter how precise the players, they’re each slightly differently tuned, and none of the strings are resonating exactly in phase. The Solina mimics this by detuning each oscillator, naturally, and by moving them in and out of phase with each other. If you want to dig into the details of how exactly [Jan]’s Solina works, he explains it well in this blog post.

Again, I’ve converted it for direct-serial control, and you can control the envelope, detune, LFO speed, and modulation depth over the serial port. Press the spacebar once to simulate a keypress, and again to let go. Try the Solina with detune and pitch modulation around twenty, and play with the LFO rate and other parameters. That’s a lot of useful noise for just some sawtooth waves.

Keyboards and What’s Next

swissonic49[Jan]’s builds are much more than what we’re demonstrating here, of course. His blog kicks off (in 2009!) with a project that essentially shoe-horns a PC into a keyboard enclosure, and the Solina and others get their own keys too. We’ve just presented the kernel of any such project — there’s a lot of labor-of-love left in wiring up all of the diodes necessary to do detection on a keyboard matrix, to say nothing of building enclosures, wiring up potentiometers, and making nice-looking front panels. But if you want to start down that path, you’ve at least got a good start.

[Jan]’s current project is the Minimo miniature monophonic synth that takes the Solina a step further and adds a lowpass filter with (digital) resonance to it. The resulting sounds are great, so we’re excited to see where [Jan] takes this one in the future.

Thanks again, [Jan], for opening the code up. And if any of you build something with this, be sure to post in the comments and let us all know. Since I started playing around with these, I’ve got the hankering to modularize the code up a bit and make it into something that’s even easier to adapt and modify. Maybe we’ll have to start up a Hackaday.io project — these little simple synths are just too much fun!


Filed under: Arduino Hacks, Hackaday Columns, musical hacks

It was Stardate 2267. A mysterious life form known as Redjac possessed the computer system of the USS Enterprise. Being well versed in both computer operations and mathematics, [Spock] instructed the computer to compute pi to the last digit. “…the value of pi is a transcendental figure without resolution” he would say. The task of computing pi presents to the computer an infinite process. The computer would have to work on the task forever, eventually forcing the Redjac out.

Calculus relies on infinite processes. And the Arduino is a (single thread) computer. So the idea of zeno_03running a calculus function on an Arduino presents a seemingly impossible scenario. In this article, we’re going to explore the idea of using derivative like techniques with a microcontroller. Let us be reminded that the derivative provides an instantaneous rate of change. Getting an instantaneous rate of change when the function is known is easy. However, when you’re working with a microcontroller and varying analog data without a known function, it’s not so easy. Our goal will be to get an average rate of change of the data. And since a microcontroller is many orders of magnitude faster than the rate of change of the incoming data, we can calculate the average rate of change over very small time intervals. Our work will be based on the fact that the average rate of change and instantaneous rate of change are the same over short time intervals.

Houston, We Have a Problem

In the second article of this series, there was a section at the end called “Extra Credit” that presented a problem and challenged the reader to solve it. Today, we are going to solve that problem. It goes something like this:

We have a machine that adds a liquid into a closed container. The machine calculates the amount of liquid being added by measuring the pressure change inside the container. Boyle’s Law, a very old basic gas law, says that the pressure in a closed container is inversely proportional to the container’s volume. If we makezeno_04 the container smaller, the pressure inside it will go up. Because liquid cannot be compressed, introducing liquid into the container effectively makes the container smaller, resulting in an increase in pressure. We then correlate the increase in pressure to the volume of liquid added to get a calibration curve.

The problem is sometimes the liquid runs out, and gas gets injected into the container instead. When this happens, the machine becomes non-functional. We need a way to tell when gas gets into the container so we can stop the machine and alert the user that there is no more liquid.

One way of doing this is to use the fact that the pressure in the container will increase at a much greater rate when gas is being added as opposed to liquid. If we can measure the rate of change of the pressure in the container during an add, we can differentiate between a gas and a liquid.

Quick Review of the Derivative

Before we get started, let’s do a quick review on how the derivative works. We go into great detail about the derivative here, but we’ll summarize the idea in the following paragraphs.

zeno_10
Full liquid add

An average rate of change is a change in position over a change in time. Speed is an example of a rate of change. For example, a car traveling at 50 miles per hour is changing its position at 50 mile intervals every hour. The derivative gives us an instantaneous rate of change. It does this by getting the average rate of change while making the time intervals between measurements increasingly smaller.

Let us imagine a car is at mile marker one at time zero. An hour later, it is at mile marker 50. We deduce that the average speed of the car was 50 miles per hour. What is the speed at mile marker one? How do we calculate that? [Issac Newton] would advise us to start getting the average speeds in smaller time intervals. We just calculated the average speed between mile marker 1 and 50. Let’s calculate the average speed between mile marker’s 1 and 2. And then mile marker’s 1 and 1.1. And then 1 and 1.01, then, 1.001…etc. As we make the interval between measurements smaller and smaller, we begin to converge on the instantaneous speed at mile marker one. This is the basic principle behind the derivative.

Average Rate of Change

zeno_11
Gas enters between time T4 and T5

We can use a similar process with our pressure measurements to distinguish between a gas and a liquid. The rate of change units for this process is PSI per second. We need to calculate this rate as the liquid is being added. If it gets too high, we know gas has entered the container. First, we need some data to work with. Let us make two controls. One will give us the pressure data for a normal liquid add, as seen in the graph above and to the left. The other is the pressure data when the liquid runs out, shown in the graph on the right. Visually, it’s easy to see when gas gets in the system. We see a surge between time’s T4 and T5.  If we calculate the average rate of change between 1 second time intervals, we see that all but one of them are less that 2 psi/sec. Between time’s 4 and 5 on the gas graph, the average rate of change is 2.2 psi/sec. The next highest change is 1.6 psi/sec between times T2 and T3.

So now we know what we need to do. Monitor the rates of change and error out when it gets above 2 psi/sec.

Our psuedo code would look something like:

pressure = x;
delay(1000);
pressure = y
rateOfChange = (y - x);
if (rateOfChange > 2)
digitalWrite(13, HIGH);  //stop machine and sound alarm

Instantaneous Rate of Change

It appears that looking at the average rate of change over a 1 second time interval is all we need to solve our problem. If we wanted to get an instantaneous rate of change at a specific time, we need to make that 1 second time interval smaller. Let us remember that our microcontroller is much faster than the changing pressure data. This gives us the ability to calculate an average rate of change over very small time intervals. If we make them small enough, the average rate of change and instantaneous rate of change are essentially the same.

Therefore, all we need to do to get our derivative is make the delay smaller, say 50ms. You can’t make it too small, or your rate of change will be zero. The delay value would need to be tailored to the specific machine by some old fashioned trial and error.

Taking the Limit in a Microcontroller?

One thing we have not touched on is the idea of the limit within a microcontroller. Mainly, because we don’t need it. Going back to our car example, if we can calculate the average speed of the car between mile marker one and mile marker 0.0001, why do we need to go though a limiting process? We already have our instantaneous rate of change with the single calculation.

One can argue that the idea behind the derivative is to converge on a single number while going though a limiting process. Is it possible to do this with incoming data of no known function? Let’s try, shall we? We can take advantage of the large gap between the incoming data’s rate of change and the processor’s speed to formulate a plan.

Let’s revisit our original problem and set up an array. We’ll fill the array with pressure data every 10ms. We wait 2 seconds and obtain 200 data points. Our goal is to get the instantaneous rate of change of the middle data point by taking a limit and converging on a single number.

We start by calculating the average rate of change between data points 200 and 150. We save the value to a variable. We then get the rate of change between points 150 and 125. We then compare our result to our previous rate by taking the difference. We continue this process of getting the rate of change between increasingly smaller amounts of time and comparing them by taking the difference. When the difference is a very small number, we know we have converged on a single value.

We then repeat the process in the opposite direction. We calculate the average rate of change between data points 0 and 50. Then 50 and 75. We continue the process just as before until we converge on a single number.

If our idea works, we’ll come up with two values that would look something like 1.3999 and 1.4001 We say our instantaneous rate of change at T1 is 1.4 psi per second. Then we just keep repeating this process.

Now it’s your turn. Think you have the chops to code this limiting process?


Filed under: Arduino Hacks, Hackaday Columns

The Arduino software environment, including the IDE, libraries, and general approach, are geared toward education. It’s meant as a way to introduce embedded development to newbies. This is a great concept but it falls short when more serious development or more advanced education is required. I keep wrestling with how to address this. One way is by using Eclipse with the Arduino Plug-in. That provides a professional development environment, at least.

The code base for the Arduino is another frustration. Bluntly, the use of setup() and loop() with main() being hidden really bugs me. The mixture of C and C++ in libraries and examples is another irritation. There is enough C++ being used that it makes sense it should be the standard. Plus a good portion of the library code could be a lot better. At this point fixing this would be a monumental task requiring many dedicated developers to do the rewrite. But there are a some things that can be done so let’s see a couple possibilities and how they would be used.

The Main Hack

As mentioned, hiding main() bugs me. It’s an inherent part of C++ which makes it an important to learning the language. Up until now I’d not considered how to address this. I knew that an Arduino main() existed from poking around in the code base – it had to be there because it is required by the C++ standard. The light dawned on me to try copying the code in the file main.cpp into my own code. It built, but how could I be sure that it was using my code and not the original from the Arduino libraries? I commented out setup() and it still built, so it had to be using my version otherwise there’d be an error about setup() being missing. You may wonder why it used my version.

When you build a program… Yes, it’s a “program” not a “sketch”, a “daughter board” not a “shield”, and a “linker” not a “combiner”! Why is everyone trying to change the language used for software development?

When you build a C++ program there are two main stages. You compile the code using the compiler. That generates a number of object files — one for each source file. The linker then combines the compiled objects to create an executable. The linker starts by looking for the C run time code (CRTC). This is the code that does some setup prior to main() being called. In the CRTC there will be external symbols, main() being one, whose code exists in other files.

The linker is going to look in two places for those missing symbols. First, it loads all the object files, sorts out the symbols from them, and builds a list of what is missing. Second, it looks through any included libraries of pre-compiled objects for the remaining symbols. If any symbols are still missing, it emits an error message.

If you look in the Arduino files you’ll find a main.cpp file that contains a main() function. That ends up in the library. When the linker starts, my version of main() is in a newly created object file. Since object files are processed first the linker uses my version of main(). The library version is ignored.

There is still something unusual about main(). Here’s the infinite for loop in main():

	for (;;) {
		loop();
		if (serialEventRun) serialEventRun();
	}

The call to loop() is as expected but why is there an if statement and serialEventRun? The function checks if serial input data is available. The if relies on a trick of the tool chain, not C++, which checks the existence of the symbol serialEventRun. When the symbol does not exist the if and its code are omitted.

Zapping setup() and loop()

Now that I have control over main() I can address my other pet peeve, the setup() and loop() functions. I can eliminate these two function by creating my own version of main(). I’m not saying the use of setup() and loop() were wrong, especially in light of the educational goal of Arduino. Using them makes it clear how to organize an embedded system. This is the same concept behind C++ constructors and member functions. Get the initialization done at the right time and place and a good chunk of software problems evaporate. But since C++ offers this automatically with classes, the next step is to utilize C++’s capabilities.

Global Instantiation

One issue with C++ is the cost of initialization of global, or file, scope class instances. There is some additional code executed before main() to handle this as we saw in the article that introduced classes. I think this overhead is small enough that it’s not a problem.

An issue that may be a problem is the order of initialization. The order is defined within a compilation unit (usually a file) from the first declaration to the last. But across compilation units the ordering is undefined. One time all the globals in file A may be initialized first and the next time those in file B might come first. The order is important when one class depends on another being initialized first. If they are in different compilation units this is impossible to ensure. One solution is to put all the globals in a single compilation unit. This may not work if a library contains global instances.

A related issue occurs on large embedded computer systems, such as a Raspberry Pi running Linux, when arguments from the command line are passed to main(). Environment variables are also a problem since they may not be available until main() executes. Global instance won’t have access to this information so cannot use it during their initialization. I ran into this problem with my robots whose control computer was a PC. I was using the robot’s network name to determine their initial behaviors. It wasn’t available until main() was entered, so it couldn’t be used to initialize global instances.

This is an issue with smaller embedded systems that don’t pass arguments or have environment values but I don’t want to focus only on them. I’m looking to address the general situation that would include larger systems so we’ll assume we don’t want global instances.

Program Class

The approach I’m taking and sharing with you is an experiment. I have done something similar in the past with a robotics project but the approach was not thoroughly analyzed. As often happens, I ran out of time so I implemented this as a quick solution. Whether this is useful in the long run we’ll have to see. If nothing else it will show you more about working with C++.

My approach is to create a Program class with a member run() function. The setup for the entire program occurs in the class constructor and the run() function handles all the processing. What would normally be global variables are data members.

Here is the declaration of a skeleton Program class and the implementation of run():

class Program {
public:
	void run();
	static Program& makeProgram() {
		static Program p;
		return p;
	}

private:
	Program() { }
	void checkSerialInput();
};

void Program::run() {
	for (;;) {
		// program code here
		checkSerialInput();
	}
}

We only want one instance of Program to exist so I’ve assured this by making the constructor private and providing the static makeProgram() function to return the static instance created the first time makeProgram() is called. The Program member function checkSerialInput() handles checking for the serial input as discussed above. In checkSerialInput() I introduced an #if block to eliminate the actual code if the program is not using serial input.

Here is how Program is used in main.cpp:


void arduino_init() {
	init();
	initVariant();
}

int main(void) {
	arduino_init();
	Program& p = Program::makeProgram();
	p.run();
	return 0;
}

The function initArduino() is inlined and handles the two initialization routines required to setup the Arduino environment.

One of the techniques for good software development is to hide complexity and provide a descriptive name for what it does. These functions hide not only the code but, in one case, the conditional compilation.

Redbot Line Follower Project

redbotThis code experiment uses a Sparkfun Redbot setup for line following. This is a two wheeled robot with 3 optical sensors to detect the line and an I2C accelerometer to sense bumping into objects. The computer is a Sparkfun Redbot Mainboard which is compatible with the Arduino Uno but provides a much different layout and includes a motor driver IC.

This robot is simple enough to make a manageable project but sufficiently complex to serve as a good test, especially when the project gets to the control system software. The basic code for handling these motors and sensors comes from Sparkfun and uses only the basic pin-level Arduino routines. I can’t possibly hack the entire Arduino code but using the Sparkfun code provides a manageable subset for experimenting.

For this article we’ll just look at the controlling the motors. Let’s start with the declaration of the Program class for testing the motor routines:

class Program {
public:
	void run();
	static Program& makeProgram() {
		static Program p;
		return p;
	}

private:
	Program() { }
	static constexpr int delay_time { 2000 };

	rm::Motor l_motor { l_motor_forward, l_motor_reverse, l_motor_pwm };
	rm::Motor r_motor { r_motor_forward, r_motor_reverse, r_motor_pwm };
	rm::Wheels wheels { l_motor, r_motor };

	void checkSerialInput();
};

There is a namespace rm enclosing the classes I’ve defined for the project, hence the rm:: prefacing the class names. On line 11 is something you may not have seen, a constexpr which is new in C++ 11 and expanded in C++14. It declares that delay_time is a true constant used during compilation and will not be allocated storage at run-time. There is a lot more to constexpr and we’ll see it more in the future. One other place I used it for this project is to define what pins to use. Here’s a sample:

constexpr int l_motor_forward = 2;
constexpr int l_motor_reverse = 4;
constexpr int l_motor_pwm = 5;
constexpr int r_motor_pwm = 6;
constexpr int r_motor_forward = 7;
constexpr int r_motor_reverse = 8;

The Motor class controls a motor. It requires two pins to control the direction and one pulse width modulation (PWM) pin to control the speed. The pins are passed via constructor and the names should be self-explanatory. The Wheels class provides coordinated movement of the robot using the Motor instances. The Motor instances are passed as references for the use of Wheels. Here are the two class declarations:

class Motor : public Device {
public:
	Motor(const int forward, const int reverse, const int pwm);

	void coast();
	void drive(const int speed);

	int speed() const {
		return mSpeed;
	}

private:
	void speed(const int speed);

	PinOut mForward;
	PinOut mReverse;
	PinOut mPwm;
	int mSpeed { };
};


class Wheels {
public:
	Wheels(Motor& left, Motor& right) :
			mLeft(left), mRight(right) {
	}

	void move(const int speed) {
		drive(speed, speed);
	}
	void pivot(const int speed) {
		drive(speed, -speed);
	}
	void stop() {
		mLeft.coast();
		mRight.coast();
	}

	void drive(const int left, const int right) {
		mLeft.drive(left);
		mRight.drive(right);
	}

private:
	Motor& mLeft;
	Motor& mRight;
};

The workhorse of Wheels is the function drive() which just calls the Motor drive() functions for each motor. Except for stop(), the other Wheels functions are utilities that use drive() and just make things easier for the developer. The compiler should convert those to a direct call to driver() since they are inline by being inside the class declaration. This is one of the interesting ways of using inline functions to enhance the utility of a class without incurring any cost in code or time.

The run() method in Program tests the motors by pivot()ing first in one direction and then the other at different speeds. A pivot() rotates the robot in place. Once the speed is set it continues until changed so the delay functions simply provide a little time for the robot to turn. Here’s the code:

void Program::run() {
	for (;;) {
		wheels.pivot(50);
		delay (delay_time);

		wheels.pivot(-100);
		delay(delay_time);

		checkSerialInput();
		if (serialEventRun) {
		}
	}
}

Wrap Up

The Redbot project is an interesting vehicle for demonstrating code techniques. The current test of the motor routines demonstrates how to override the existing Arduino main(). Even if you don’t like my approach with Program, the flexibility of using your own main() may come in handy for your own projects. The next article is going to revisit this program using templates.

THE EMBEDDING C++ PROJECT

Over at Hackaday.io, I’ve created an Embedding C++ project. The project will maintain a list of these articles in the project description as a form of Table of Contents. Each article will have a project log entry for additional discussion. Those interested can delve deeper into the topics, raise questions, and share additional findings.

The project also will serve as a place for supplementary material from myself or collaborators. For instance, someone might want to take the code and report the results for other Arduino boards or even other embedded systems. Stop by and see what’s happening.


Filed under: Arduino Hacks, Hackaday Columns, Software Development, software hacks

The language C++ is big. There is no doubting that. One reason C++ is big is to allow flexibility in the technique used to solve a problem. If you have a really small system you can stick to procedural code encapsulated by classes. A project with a number of similar but slightly different entities might be best addressed through inheritance and polymorphism.

A third technique is using generics, which are implemented in C++ using templates. Templates have some similarities with #define macros but they are a great deal safer. The compiler does not see the code inserted by a macro until after it has been inserted into the source. If the code is bad the error messages can be very confusing since all the developer sees is the macro name. A template is checked for basic syntax errors by the compiler when it is first seen, and again later when the code is instantiated. That first step eliminates a lot of confusion since error messages appear at the location of the problem.

Templates are also a lot more powerful. They actually are a Turing complete language. Entire non-trivial programs have been written using templates. All the resulting executable does is report the results with all the computation done by the compiler. Don’t worry, we aren’t going there in this article.

Template Basics

You can use templates to create both functions and classes. The way this is done is quite similar for both so let’s start with a template function example:

template<typename T, int EXP = 2>
T power(const T value, int exp = EXP) {
	T res { value };
	for (; exp > 1; --exp) {
		res *= value;
	}
	return res;
}

This is a template function for raising value by the integer exponent, exp. The keyword template is followed in angle brackets by parameters. A parameter is specified using either typename or class followed by a name, or by an integer data type followed by a name. You can also use a function or class as a template parameter but we won’t look at that usage.

The name of a parameter is used within the body of the class or function just as you would use any other type, or value. Here we use T as the type name for the input and return values of the function. The integer EXP is used to set a default value of 2 for the exponent, i.e. making power calculate the square.

When the compiler instantiates a template function or class, it creates code that is the same as a handwritten version. The data types and values are inserted as text substitutions. This creates a new version typed by the actual arguments to the parameters. Each different set of arguments creates a new function or type. For example, an instance of power() for integers is not the same as power() for floats. Similarly, as we’ll see in a moment, a class Triple for integers is not the same as one for float. Each are distinct types with separate code.

Since power() is a template function it will work directly for any numeric data type, integer or floating point. But what if you want to use it with a more complex type like the Triple class from the last article? Let’s see.

Using Templates

Here’s the declaration of Triple reduced to only what is needed for this article:

class Triple {
public:
	Triple(const int x, const int y, const int z);
	Triple& operator *=(const Triple& rhs);

	int x() const;
	int y() const;
	int z() const;

private:
	int mX { 0 };	// c++11 member initialization
	int mY { 0 };
	int mZ { 0 };
};

I switched the plus equal operator to the multiple equal operator since it is needed by the power() function.

Here is how the power() function is used for integer, float, and our Triple data types:

int p = power(2, 3);
float f = power(4.1, 2);

Triple t(2, 3, 4);
Triple res = power(t, 3);

The only requirement for using a user defined data type (UDT) like Triple with power() is the UDT must define an operator=*() member function.

Template Classes

Assume you’ve been using Triple in a project for awhile with integer values. Now a project requirement needs it for floating point values. The Triple class code is all debugged and working, and more complex than what we’ve seen here. It’s not a pleasant thought to create a new class for float. There are also hints that a long or double version might be needed.

With not much work Triple can be converted to a generic version as a template class. It’s actually fairly straightforward. Begin with the template declaration just as with the function power() and replace all the declarations of int with T. Also check member function arguments for passing parameters by value. They may need to be changed to references to more efficiently handle larger data types or UDTs. I changed the constructor parameters to references for this reason.

Here is Triple as a template class:

template<typename T>
class Triple {
public:
	Triple(const T& x, const T& y, const T& z);
	Triple& operator *=(const Triple& rhs);

	T x() const;
	T y() const;
	T z() const;

private:
	T mX { 0 };	// c++11 member initialization
	T mY { 0 };
	T mZ { 0 };
};

Not a lot of difference. Here’s how it could be used:

Triple<int> ires = power(Triple { 2, 3, 4 }, 3);
Triple fres = power(Triple(1.2F, 2.2, 3.3)); // calc square
Triple dres = power(Triple(1.2, 2.2, 3.3));// calc square
Triple lres = power(Triple(1, 2, 3.3), 2);

Unfortunately, the new flexibility comes at the cost of telling the template the data type to use for Triple. That is done by putting the data type inside brackets following the class name. If that is a hassle you can always use typedef or the new using to create an alias:

using TripleInt = Triple;
TripleInt ires = power(Triple { 2, 3, 4 }, 3);

Creating a template class like this saves debugging and maintenance costs overall. Once the code is working, it works for all related data types. If a bug is found and fixed, it’s fixed for all versions.

Template Timing and Code Size

The code generated by a template is exactly the same code as a handwritten version of the same function or class. All that changes between versions is the data type used in the instantiation. Since the code is the same as the handwritten version, the timing is going to be the same. Therefore there is no need to actually test timing. Phew!

Templates are Inline Code

Templates are inherently inline code. That means every time you use a template function or a template class member function the code is duplicated inline. Each instance with a different data type creates its own set of code, but that will be no more than if you’d written a class for each data type. There can be savings using template classes since member functions are not instantiated if they are not used. For example, if the Triple class getter functions – x(), y(), z() – are never used, their code is not instantiated. They would be for a regular class, although a smart linker might drop them from the executable.

Consider the following use of power() and Triple:

int i1 = power(2, 3);
int i2 = power(3, 3);
Triple t1 = power(Triple(1, 2, 3), 2);

This creates two inline integer versions of power even though both are instantiated for the same data type. Another instance is created for the Triple version. A single copy of the Triple class is created because the data type is always int.

Here we’re relying on implicit instantiation. That means we’re letting the compiler determine when and where the code is generated. There is also explicit instantiation that allows the developer to specify where the code is produced. This takes a little effort and knowledge of which data types are used for the templates.

Generally, implicit instantiation means inline function code with the possibility of duplication of code. Whether that matters depends on the function. When a function, not an inline function, is called there is overhead in invocation. The parameters to the function are pushed onto the stack along with the housekeeping information. When the function returns those operations are reversed. For a small function the invocation may take more code than the function’s body. In that case, inlining the function is most effective.

The power() function used here is interesting because the function’s code and the code to invoke it on an Uno are similar in size. Of course, both vary depending on the data type since large data types require more stack manipulation. On a Arduino Uno, calling power() with an int takes more code than the function. For float, the call is slightly larger. For Triple, the code to invoke is a good piece larger. On other processors the calling power() could be different. Keep in mind that power() is a really small function. Larger functions, especially member functions, are typically going to outweigh the cost to call them.

Specifying where the compiler generates the code is an explicit instantiation. This will force an out-of-line call with the associated overhead. In a source file you tell the compiler which specializations you need. For the test scenario we want them for int and Triple:

template int power(int, int);
template Triple<int> power(Triple<int>, int);

The compiler will create these in the source file. Then, as with any other function, you need to create an extern declaration. This tells the compiler to not instantiate them as inline. These declarations are just the same as above, only with extern added:

extern template int power(int, int);
extern template Triple power(Triple, int);

Scenario for Testing Code Size

It took me a bit to create a test scenario for demonstrating the code size differences between these two instantiations. The problem is the result from the power() function must be used later in the code or the compiler optimizes the call away. Adding code to use the function changes the overall code size in ways that are not relevant to the type of instantiation. That makes comparisons difficult to understand.

I finally settled on creating a class, Application, with data members initialized using the power() function. Adding data members of the same or different types causes minimal overall size changes so the total application code size closely reflects the changes only due to the type of instantiation.

Here is the declaration of Application:

struct Application {
public:
	Application(const int value, const int exp);

	static void loop() {
	}

	int i1;
	int i2;
	int i3;
	Triple t1;
	Triple t2;
	Triple t3;
};

and the implementation of the constructor:

Application::Application(int value, const int exp) :
		i1 { power(value++, exp) }, //
				i2 { power<int, 3="">(value++) }, // calcs cube
				i3 { power(value++, exp) }, //

				t1 { power(Triple(value++, 2, 3)) }, // calcs square
				t2 { power(Triple(value++, 4, 5), exp) }, //
				t3 { power(TripleInt(value++, 2, 3), exp) } //
{
}

The minimum application for an Arduino has just an empty setup and loop() functions which takes 450 bytes on a Uno. The loop() used for this test is a little more than minimum but it only creates an instance of Application and calls its loop() member function:

void loop() {
	rm::Application app(2, 3);
	rm::Application::loop();	// does nothing
}

Code Size Results

Here are the results for various combinations of implicit and explicit instantiation with different numbers of class member variables:

template code size

The first columns specify how many variables were included in the Application class. The columns under Uno and Due are the code size for those processors. They show the size for implicit instantiation, explicit instantiation of power() for just the Triple class, and explicit instantiation for both int and Triple data types.

The code sizes are dependent on a number of factors so can only provide a general idea of the changes when switching from implicit to explicit template instantiation. Actual results depend on the tool chains compiler and linker. Some of that occurs here using the Arduino’s GCC tool chain.

In all the cases with the Uno where one variable is used, the code size increases with explicit instantiation. In this case the function’s code plus the code for calling the function is, as expected, greater than the inline function’s code.

Now look at the Uno side of the table where there are 2 integers and 2 Triples, i.e. the fourth line. The first two code sizes remain the same at 928 bytes. The compiler optimized the code for the two Triples() by creating power() out-of-line without being told to do it explicitly. In the third column there is a decrease in code size when the integer version of power() is explicitly instantiated. It did the same a couple of lines below that when there are only the 2 Triples. These were verified by examing the assembly code running objdump on the ELF file.

In general, the Due’s code size did not improve with explicit instantiation. The larger word size of the Due requires less code to call a function. It would take a function larger than power() to make explicit instantiation effective in this scenario.

As I mentioned, don’t draw too many conclusions for these code sizes. I repeatedly needed to check the content of the ELF file using objdump to verify my conclusions. As a case in point, look at the Due side, with 2 integers and a Triple, with the two code sizes of 10092. They’re just coincidence. In one the integer version of power() is inlined and in the other, explicitly out-of-lined. The same occurs on the first line under Uno where there are just two integers and no Triples.

You can find other factors influencing code size. When three Triples are involved the compiler lifts the multiplication code from power(), but not the entire function. This isn’t because power() is a template function but just a general optimization, i.e. lifting code from inside a loop.

Wrap Up

Templates are a fascinating part of C++ with extremely powerful capabilities. As mentioned above, you can write an entire program in templates so the compiler actually does the computation. The reality is you probably are not going to be creating templates in every day programming. They are better suited for developing libraries and general utilities. Both power() and Triple fall into, or are close to, that category. This is why the C++ libraries consist of so many template classes. Creating a library requires attention to details beyond regular coding.

It’s important to understand templates even if you don’t write them. We’ve discussed some of the implications of usage and techniques for making optimal use of templates because they are an inherent part of the language. With them being such a huge part of C++ we’ll come back to them again to address places where they can be used.

The Embedding C++ Project

Over at Hackaday.io, I’ve created an Embedding C++project. The project will maintain a list of these articles in the project description as a form of Table of Contents. Each article will have a project log entry for additional discussion. Those interested can delve deeper into the topics, raise questions, and share additional findings.

The project also will serve as a place for supplementary material from myself or collaborators. For instance, someone might want to take the code and report the results for other Arduino boards or even other embedded systems. Stop by and see what’s happening.


Filed under: Arduino Hacks, Hackaday Columns, Software Development

For many embedded C developers the most predominate and questionable feature of C++ is the class. The concern is that classes are complex and therefore will introduce code bloat and increase runtimes in systems where timing is critical. Those concerns implicate C++ as not suitable for embedded systems. I’ll bravely assert up front that these concerns are unfounded.

When [Bjarne Stroustrup] created C++ he built it upon C to continue that language’s heritage of performance. Additionally, he added features in a way that if you don’t use them, you don’t pay for them.

Data Hiding

Prior to the object-oriented paradigm shift in, roughly, the early 90s, structured programming was the technique to use. One of the principles that came with it was data or information hiding.

A good example for C programmers is the FILE pointer (FILE*). The only thing you know about a FILE* is that it points to a data structure somewhere in a library. You can open, read, write, and otherwise manipulate a FILE* through a set of functions. The actual data about the file you’re working with is hidden. In a sense, this is a step toward object- oriented programming. The FILE* points to the object, a struct, and the functions are the class methods that operate on the object, or instance.

[Stroustrup] took C’s struct and extended it to create a class based form of object-orientation. He might have taken another approach since there are other forms of object- orientation. For instance, if you work heavily with JavaScript you’re doing prototype object- oriented development.

Let’s look at classes and their non-existent code bloat in this article. We’ll encounter some other features of C++ along the way. I’m compiling with C++11 as implemented by the GNU Project GCC compilers to obtain the latest features of the language. I chose it because it’s the compiler used by the Arduino family of boards and can be used by the Raspberry Pi. It is often available for other processors, making it well suited for the hacker community.

I’ll be compiling the code for both an Uno and a Due board to illustrate that the type of processor is irrelevant. The Uno uses an ATmega328P 8-bit processor and the Due an ATSAM3X8E ARM Cortex-M3 CPU 3- bit processor, so there is quite a difference between them.

Declaring Classes

Classes are user defined types (UDTs). In C++ classes, structs, unions, and enums are all UDTs. A UDT is the equal of the data types you are familiar with in C: integer, char, float, double, etc. UDTs act just like built in data types in C++ statements: initialization, function calls, function return values. Operations on UDTs mimic the built in operations: arithmetic operations, logical operations. It was a design goal for C++ that UDTs and regular data types operate with no noticeable differences.

[Elliot] discussed ring buffers in a recent article, Embed with Elliot: Going ‘Round with Circular Buffer, so I borrowed his C code with a few modifications and created this equivalent C++ class:

namespace had {

using uint8_t = unsigned char;
const uint8_t bufferSize = 16;

class RingBuffer {
	uint8_t data[bufferSize];
	uint8_t newest_index;
	uint8_t oldest_index;

public:
	enum BufferStatus {
		OK, EMPTY, FULL
	};

	RingBuffer();

	BufferStatus bufferWrite(const uint8_t byte);
	enum BufferStatus bufferRead(uint8_t& byte);
};
}

The first new C++ features in the code are the namespace and using keywords. They aren’t specific to classes so let me defer explaining them for a few paragraphs.

A class declaration begins with the keyword class followed by a name, just as C creates structs. In fact, struct could be used here instead of class. The difference between the two is struct, by default, provides public access to data and member functions while a class restricts access by default.

The next three lines declare data members of the class exactly as you would do with a struct in C. Since this is a class the members are private and cannot be accessed from outside the class. This is how C++ supports and stringently enforces data hiding.

The public keyword says the following lines are openly available. These can be accessed outside the class. You can also use private in the same way as public to make the following lines not accessible. A third access keyword is protected but it is used for class inheritance, a more advanced discussion, and we’ll ignore it for now. These access control keywords can be mixed as you wish in a class.

Next an enum is specified. Here it works just like a C enum.

The next line declares the class constructor. The purpose of a constructor is, in my vernacular, to make the class sane when it is created. It should set all the variables in the class to default starting values and contain code that sets up the class for proper operation. That may mean allocating dynamic memory for the class to use. For instance, RingBuffer could be setup to handle buffers of a chosen length instead of a globally defined fixed length. The length would be passed as an argument to the constructor and used to size the dynamically allocate memory.

The next two lines are member functions for writing and reading bytes of data to and from the buffer, the array data, in the class. There is no difference between these declarations and similar ones in C, except for one more C++ feature that is again not specific to classes, the & in the parameter declaration for bufferRead(uint8_t& byte). The & indicates the parameter is passed by reference. We’ll add that to the list of additional features to discuss below.

These are the basics for classes as UDTs. There are a lot of details about their design and implementation but those are beyond the scope of this article. A key point is that a class encapsulates within it all the capabilities you would provide for a data structure in C.

Using the Class

The code using RingBuffer is just a skeleton to illustrate how classes are used:

had::RingBuffer r_buffer;

void setup() {
}

void loop() {
	uint8_t tempCharStorage;
	// Fill the buffer
	for (int i = 0; r_buffer.bufferWrite('A' + i) == had::RingBuffer::OK; i++) {
	}
	// Read the buffer
	while (r_buffer.bufferRead(tempCharStorage) == had::RingBuffer::OK) {
	}
}

Line 1 of the code is the definition of a RingBuffer variable. The had:: is a scoping operation that tells the compiler to use the RingBuffer declared in the had namespace. Similarly, on lines 9 and 12, the enums OK are scoped in had.

Calls to class member functions use the same dot-notation that C uses for accessing members of structs. The calls are just r_buffer.bufferWrite and r_buffer.bufferRead. If you want to call a class member function from a pointer to a variable the arrow-notation is used. Except for that adaptation, member functions calls are the same as C calls.

Behind the scenes, the compiler is passing r_buffer as a hidden parameter to the member functions. It is passed as a pointer and within the functions is accessed by the name this. You can access the member data using the this pointer like this->newest_index but it is typically unnecessary. There are situations where it is used.

C Version of Code

For completeness let’s look at the C version of the code. It’s remarkably similar. Here are the declarations:

typedef unsigned char uint8_t;

enum BufferStatus {BUFFER_OK, BUFFER_EMPTY, BUFFER_FULL};
#define BUFFER_SIZE 16

struct LifoBuffer {
	uint8_t data[BUFFER_SIZE];
	uint8_t newest_index;
	uint8_t oldest_index;
};

void initBuffer(struct LifoBuffer* buffer);
enum BufferStatus bufferWrite(struct LifoBuffer* buffer, uint8_t byte);
enum BufferStatus bufferRead(struct LifoBuffer* buffer, uint8_t *byte);

We’ve got a typedef instead of the using, and a define instead of a const. After that LifoBuffer defines the same data, and the function declarations are about the same. The initBuffer serves basically the same purpose as the constructor. And we see a pointer instead of a reference.

One difference is the explicit passing of the pointer to the data structure. That is the same as the hidden this that C++ passes to member functions.

The calling routines look very similar also:

struct LifoBuffer buffer;

void setup() {
	initBuffer(&buffer);
}

void loop() {
	uint8_t tempCharStorage;
	// Fill the buffer
	uint8_t i = 0;
	for (; bufferWrite(&buffer, 'A' + i) == BUFFER_OK; i++) {
	}
	// Read the buffer
	while (bufferRead(&buffer, &tempCharStorage) == BUFFER_OK) {
	}
}

Source Files

Sorry to disappoint, but I’m not going to post the complete source files. You wouldn’t see any more difference than in the calling routines. But here is a snippet from each to satisfy your curiosity. I’ll show the bufferRead function so you can see how the reference parameter is handled. First the C++:

RingBuffer::BufferStatus RingBuffer::bufferRead(uint8_t byte) {
	if (newest_index == oldest_index) {
		return EMPTY;
	}

	byte = data[oldest_index];
	oldest_index = nextIndex(oldest_index);

	return OK;
}

Now the C version:

enum BufferStatus bufferRead(struct LifoBuffer* buffer, uint8_t *byte) {
	if (buffer->newest_index == buffer->;oldest_index) {
		return BUFFER_EMPTY;
	}

	*byte = buffer->data[buffer>oldest_index];
	buffer->oldest_index = nextIndex(buffer->oldest_index);

	return BUFFER_OK;
}

The major difference is the C++ version looks cleaner without the pointer dereferencing operators needed in C to access the buffer data structure. The parameter byte, the reference, also is accessed more easily. The main drawback with the C++ version is the need for the scoping operator, the ::, necessary to tell the compiler the functions and enums are part of the RingBuffer class.

There are two advantages to having the BufferStatus enum within the class RingBuffer that make using the scoping operator worth the effort. First, the enum names are shortened by having the buffer_ prefix removed. The scoping operator tells the developer and the compiler when these status values are valid. Second, it avoids name conflicts that can cause confusion. You might have other classes that use a status of OK or FAIL. Those may not use the same underlying values. If those classes are buried in a library you have no way of changing their values. One may say OK‘s value is 1, and the other 4. The scoping operator sorts out that problem, and the compiler enforces it by refusing to allow an enum from one class to be used with another.

Additional C++ Features

Let’s back up and look at the additional features of C++ we’ve encountered: namespaces, using, and references.

Namespaces

I didn’t intend to introduce namespaces in this article but the need to use them came up when I compiled the C++ code for the Due. I’d been compiling for the Uno without any problems; but when I switched to the Due, the compiler generated errors that it took me a few moments to understand: my RingBuffer class name was clashing with a RingBuffer class name used by the Due for serial communications.

Name clashes amongst libraries and user code is exactly the reason for having namespaces. I could have changed the name of my class to FifoBuffer which is actually a better name because it describes the usage while RingBuffer describes the implementation. Another name, more Computer Science oriented, is queue. I didn’t use it because the C++ standard library implementation of a FIFO is named queue. I left it at RingBuffer so I could discuss namespaces.

Creating a namespace is easy:

namespace <name> { 
// some code }

So is using one:

using namespace <name> {
// some code
}

I wrapped the entire header file, RingBuffer.h, and the source file, RingBuffer.cpp, in the namespace had, for HackADay.

In the Application.cpp file where I used the RingBuffer class I needed to qualify the constructor and the uses of the BufferStatus enums with the had namespace so the compiler knew I wanted them, not the ones from the library.

Aliases: Using and References

Both the using keyword and references create aliases. The ability to create aliases is a general feature of C++ that was extended and improved in C++11. For the most part, aliases allow the use of simpler names to refer to more complex expressions.

Using

The using keyword creates an alias for a complex data type. Here the type unsigned char is given the alias uint8_t. This usage replaces the use of typedef, which still available to not break legacy code. If this simple example doesn’t impress you how about having an alias to simplify const unsigned long int* const or a pointer to a function with a large number of parameters.

Here are the two lines of code from above:

using uint8_t = unsigned char;
const uint8_t  bufferSize = 16;

Notice how the statements are similar. The second line creates the variable bufferSize and initializes it to the value 16. The first line creates the name uint8_t and sets it to the data type unsigned char. This parallelism of the constructs is why using was introduced. A big effort in C++11 was the standardizing of expression forms along these lines.

References

References are a feature of C++ that appear in many places. Since this is not a tutorial on C++ I won’t elaborate beyond their use as a function parameter.

Function arguments can be passed in multiple ways. One way is by value. This is the usual way in C/C++ for arguments: a copy of the value from the argument variable is passed. Any operations within the function modify the local value but have no affect on the argument variable.

C/C++ can also pass arguments by pointer, which is a form of reference passing. Operations affect the original value. We know that pointers are dangerous so C++ wanted to minimize their use.

A reference is an alias of the argument variable. Just as with a pointer the address of the argument variable is passed. The big difference is you cannot manipulate this address since it is not exposed as with a pointer. The original value of the argument variable is affected by any operations in the function.

Cost of Classes

I teased above about showing that there is no cost to using classes. This is 99.9999%, or something around there, true. In this article I’m only going to look at code size because someone looking at C++ classes and seeing their additional complexity expects there has to be a cost.

I used Eclipse with the Arduino plugin mentioned in Code Craft: Using Eclipse For Arduino Development to compile the code for the Arduino Uno and Due. Here are the results:

code bloat

Clearly there is no major code bloat when using C++ on either processor. Let’s walk through the table first for the Uno and then come back to look at the Due results.

The line Buffer Routines is the code size for just the FIFO buffer code and empty Arduino setup() and loop() routines. I did this only for the Uno because I was too lazy to go back and strip the Due version down to the minimum. As we’ll see, it doesn’t matter.

The next line, File Scope Data, has the definitions of the data structures at file scope in the Application source file. The C++ code is 38 bytes larger because the class constructor is called. In order to call the constructor additional code is executed before main() is called. In any C/C++ application there is system specific initialization code executed to setup the application. C++ just adds a little more to call all the file scope constructors.

The next line shows that it is the initialization code as I suggested. An additional 4 data structures were added to both programs, with calls to their initialization inserted in the C version. The difference between the two versions remains at 38. That is a fixed overhead you’ll see on an Uno for using C++.

In the final line, I moved the definition of the data structure, and initialization for the C version, into loop(). That takes them out of file scope which means the C++ special initialization code is not needed. Now both versions have the same code size.

So, at least for the Uno, I rest my case. C++ classes do not cause code bloat.

The results for the Due are identical except for the case with multiple data structures at file scope. There is a 12 byte overhead for having a single data structure at file scope. Okay,I assumed that’s the C++ pre-main() initialization code. But that overhead reduced to only 4 bytes when the additional 3 data structures were added. What? This deserved additional investigation.

I went back to having one data structure at file scope then added more one at a time, recording the increase in code size. The C version alternately increases by 8 and 16 bytes. The C++ version increases by 16 bytes for the second data structure and by 8 bytes for each one after that. I could generate some guesses on this but frankly it’s not worth the effort since these differences are small.

As with the Uno, the final line demonstrates there is no code bloat. This is when the data structures and initialization are moved to within loop().

There it is. No code bloat from using classes in embedded systems.

Wrap Up

I just scratched the surface explaining classes in this article. I wanted to provide enough explanation so C developers would understand the concepts sufficiently to accept classes are not going to increase code size. More details would just be confusing, and there are a lot more details. I also don’t want to play language lawyer so the presentation is pragmatic, not pedantic.

Software development is a complex process. A continuing goal for language developers has been to provide a tool that is efficient to use both in writing and executing code. C++ classes not only are efficient in code size but they help avoid common errors made during development. One measure of development is that rate at which bugs are fixed. Even better is preventing bugs from occurring.

The class constructor is a bug preventor. When you instantiate a class the constructor is going to be called to initialize the variable. Consider the situation with the C code where I created FifoBuffer a number of times. For each of those variables I needed to add the call to init(). It’s very easy to forget that initialization, especially if you create the variable in a file other than where the initialization is to take place, like the setup() in an Arduino application.

The Embedding C++ Project

Over at Hackaday.io, I’ve created an Embedding C++ project. The project will maintain a list of these articles in the project description as a form of Table of Contents. Each article will have a project log entry for additional discussion. Those interested can delve deeper into the topics, raise questions, and share additional findings.

The project also will serve as a place for supplementary material from myself or collaborators. For instance, someone might want to take the code and report the results for other Arduino boards or even other embedded systems. Stop by and see what’s happening.


Filed under: Arduino Hacks, Hackaday Columns, Raspberry Pi, Software Development

As we work on projects we’re frequently upgrading our tools. That basic soldering iron gives way to one with temperature control. The introductory 3D printer yields to one faster and more capable. One reason for this is we don’t really understand the restrictions of the introductory level tools. Sometimes we realize this directly when the tool fails in a task. Other times we see another hacker using a better tool and realize we must have one!.

The same occurs with software tools. The Arduino IDE is a nice tool for starting out. It is easy to use which is great if you have never previously written software. The libraries and the way it ties nicely into the hardware ecosystem is a boon.

When you start on larger projects, say you upgrade to a Due or Teensy for more code or memory space, the Arduino IDE can hamper your productivity. Moving beyond these limitations requires a new, better tool.

Where do we find a better tool? To begin, recognize, as [Elliot] points out that There is no Arduino “Language”, we’re actually programming in C or C++. We chose which language through the extension on the file, ‘c’ for C and ‘cpp’ for C++. An Arduino support library may be written in C or C++ depending on the developer’s preference. It’s all mix ‘n match.

Potentially any environment that supports C/C++ can replace the Arduino IDE. Unfortunately, this is not easy to do, at least for inexperienced developers, because it means setting up the language tool chain and tools for uploading to the board. A developer with that much experience might eschew an integrated development environment altogether, going directly to using makefiles as [Joshua] describes in Arduino Development; There’s a Makefile for That.

The reality is the Arduino IDE is not much more than a text editor with the ability to invoke the tools needed to compile and download the code to the Arduino. A professional IDE not only handles those details but provides additional capabilities that make the software development process easier.

Eclipse CDT & Arduino Plug-In

Eclipse IDE

An alternative to the Arduino IDE is Eclipse, a development environment used by professional and hobby developers. It’s open-source software and extensible via plugins. Many developers have contributed to its development, including some with corporate support.

Eclipse based Arduino development uses two additions to the basic Eclipse IDE. One is the C/C++ Development Tooling (CDT). The CDT not only adds the C/C++ development capability but tools for automatic code completion and insertion, and also some code refactoring. Trust me, once you understand how to use these capabilities you’ll miss them dearly when not available.

The other addition is a plug-in developed by [Jantje Baeyens]. The plug-in is free and open-source.

This setup works in combination with the build environment for the Arduino IDE. You still need the IDE installed; you just don’t have to use it.

Earlier this year I installed Eclipse Luna with the plug-in and the Arduino 1.6.0 IDE while running Ubuntu 14.04. I just followed the installation directions on the Eclipse and plug-in sites and it went smoothly. Since then [Jantze] released a version of Eclipse Luna with the latest version of the plug-in pre-installed. I downloaded it and the 1.6.5r5 Arduino IDE recently. It works fine and installing updates for the plug-in is handled automatically by Eclipse.

When making a switch like this you need to know both where the current tool is inadequate, how the new tool addresses those limitations, and what additional benefits will accrue. We’ll address the limitations and how they are addressed first, and then the added benefits.

Arduino IDE Limitations

 

Editor Tabs

When projects get larger they obviously have more lines of code. Having hundreds or thousands of lines of code in a single file is a nightmare. Scrolling through that large a file to find a single line of code is time consuming. That is why compilers support splitting code into multiple files. Moving between editor windows is far easier than scrolling.

The Arduino IDE supports multiple files by adding more tabs. If you use INO files you’re only adding one at a time, but if you use C/C++ header and source files it’s two at time. With the Arduino IDE all the files have to be in open windows in order to be processed by the compiler. Sooner or later you run out of space across the top of the screen for more tabs.

eclipse project explorerMy 23″ monitor supports around 18 tabs and my 19″ side monitor about a dozen. Tabs for additional files scroll off to the right. They can be reached using Ctrl-ALT-Right, or through a drop down list on the right, which is cumbersome to use. To add insult, on my Ubuntu system the Ctrl-ALT-Right is used for changing workspaces so cannot be used for changing tabs.

Eclipse also uses tabs but they are only involved with editing. The files for a project are listed in a Project Explorer sub-window. Any file can be opened in the editor and closed when the editing or viewing is done. Having only the files open pertinent to your current activity reduces distractions. Eclipse also allows access to multiple projects to be available at the same time. This is useful if you want to get code snippets for your current project from an older one, or if you are working on two Arduinos that cooperate with one another.

Compilation Speed

The Arduino IDE copies every file to a temporary directory as an early step in the build process. This forces the build environment to see every file as changed, which in turn means the files are all compiled.

Under Eclipse the build does not move the files. The tool chain recognizes that once a file is compiled it does not need to be compiled again until a change is made in the source. In extremely large commercial projects this can literally save hours of time. Even in large hobby projects the time savings can be substantial.

Hunting for Errors

The console at the bottom of the Arduino IDE displays the compilation process and the errors that occur. The errors are listed with the file, line number, and the column of the error:

somefile.cpp:11:3: error: expected '}' before 'else'

To fix the error you need to find the file – ouch! if it’s on the drop down list – and then find the line in the file. This is time consuming.

Eclipse reports errors in two ways. The first is a console window similar to the one for the Arduino. The difference is you can click on an error and be taken to the line of code. Eclipse will even open the file if it’s not currently active in an editor. A real time saver.

The second is a list of errors in a “Problems” window stripped of all the compiler gobbledygook. Reading this list is much quicker than either IDE’s console window. By scanning the list you may see that the reported error is not the error that needs to be fixed. Sometimes errors, typos for example, are reported in multiple locations but the correction is elsewhere. The console window is still important because it provides the additional information that is sometimes needed to understand exactly what is causing the problem.

problem window

Terminal Annoyance

An annoyance with the Arduino IDE is the need to shut down the serial port terminal when you want to upload new code. The Eclipse solution manages this while keeping the terminal window open.

Note: This appears to have changed from the 1.60 to the 1.6.5 version of the Arduino IDE. If you are working with an older version and sticking with the Arduino IDE you should upgrade to the latest.

Eclipse Enhancements

Eclipse provides enhancements in addition to the improvements discussed above. Some of these are capabilities you don’t realize you need, but will love once you have them.

new class dialogCode completion is a simple enhancement that saves keystrokes and prevents errors by adding closing braces, quotes, brackets, parentheses, etc. This reduces errors due to omissions, and helps keep code better organized. (You do put braces around your if-clauses, don’t you? Apple didn’t, which created a security hole in their SSL processing, although there were a number of other problems with that code.)

As you’re working you often realize the name of a function, variable, or class is not exactly right. It needs to change. Hunting down a name in multiple files is daunting so you just let it go. Eclipse allows you to select a name, tell it to make the change, and all the occurrences will be changed.

Adding a new class requires creating new header and source files. A wizard does this for you. You enter the class name, a base class name if needed, and select if you want the constructor and destructor created. The files are created with skeleton source code and added to the project.

Wizards also can create new source or header files.

Creating the body of a function or class member is also automated once the function is declared. You first create the declaration in the header file:

 int something(const int a); 

and then you right click, select ‘Source’ and ‘Implement Method’. A skeleton definition is inserted into the source file:

int something(const int a) {
}

This is especially handy when the function has a long list of parameters.

Often you realize that some lines of code would be better as a new function. This may be so they can be reused in other locations, or just to simplify the flow in the current location. Lifting the code into a new function just requires selecting the code, right clicking, selecting ‘Refactor’, and ‘Extract Function’. A wizard opens for you to approve the new functions parameter list and when you accept this a call to the function replaces the lines and the new function is created.

To illustrate, one set of the duplicated code in loop() can be extracted into a function, outPins, and the duplicate code can be manually replaced with a call to the new function. Not an earth shaking example, admittedly, but it demonstrates the possibilities. The code starts as:

void loop() {
	static unsigned char cnt = 0;
	static bool state = false;

	analogWrite(pin09, cnt);
        
	// code to extract to make new function
	digitalWrite(pin11, state);
	digitalWrite(pin13, state);
	delay(blink_time);

	state = !state;

	// duplicate code
	digitalWrite(pin11, state);
	digitalWrite(pin13, state);
	delay(blink_time);
}

and after the refactoring becomes:

void loop() {
	static unsigned char cnt = 0;
	static bool state = false;

	analogWrite(pin09, cnt);

	outPins(state);
	state = !state;
	// replace next three lines with outPins(state);
	digitalWrite(pin11, state);
	digitalWrite(pin13, state);
	delay(blink_time);
}

and after a little cut and paste loop() becomes much simpler and maintenance of the lines now in outPins() is easier:

 
void loop() {
	static unsigned char cnt = 0;
	static bool state = false;

	analogWrite(pin09, cnt);
	outPins(state);
	state = !state;
	outPins(state);
}

Many of these capabilities are refactoring of code, a complex topic that is well worth studying if you will be working on larger projects. The techniques involved improve your code organization without changing the operation.

Caution: Eclipse will make the change you ask for so be sure you have it right. Fixing a massive automatic change can be a nightmare. Been there, done that.

This is just an overview of the advantages of using Eclipse in larger projects. If you are familiar with Eclipse chime in with other capabilities in the comments.

Plug-in Niceties

plugin dialogAll the above is what Eclipse brings. The Arduino plugin also provides a dialog that gives you control over the development parameters by replacing the Arduino IDE drop down menus. You no longer have to go to the menu to first select the board and then go back up to select the port. Also, the dialog allows you to specify compiler options that are buried down in a configuration file with the Arduino IDE. For instance, you can change from the standard optimizing for space to optimizing for speed.

An addition the plug-in brings is an ‘oscilloscope’ graphing window that displays properly formatted data as a curve. This is good for seeing how sensors are reacting to the environment.

Wrap Up

I’ve switched completely to using Eclipse for my Arduino projects. I was already comfortable with Eclipse for other projects so it felt good returning to it for the Arduino. The refactoring and auto-code completion were sorely missed and the other features are icing on the cake.


Filed under: Arduino Hacks, Hackaday Columns, Raspberry Pi, Software Development

For over ten years, Arduino has held onto its popularity as “that small dev-board aimed to get both artists and electronics enthusiasts excited about physical computing.” Along the way, it’s found a corner in college courses, one-off burning man rigs, and countless projects that have landed here. Without a doubt, the Arduino has a cushy home among hobbyists, but it also lives elsewhere. Arduino lives in engineering design labs as consumer products move from feature iterations into user testing. It’s in the chem labs when scientists need to get some sensor data into their pc in a pinch. Despite the frowns we’ll see when someone blinks an LED with an Arduino and puts it into a project box, Arduino is here to stay. I thought I’d dig a little bit deeper into why both artists and engineers keep revisiting this board so much.

Arduino, do we actually love to hate it?

do-we-love-arduinoIt’s not unusual for the seasoned engineers to cast some glares towards the latest Arduino-based cat-feeding Kickstarter, shamelessly hiding the actual Arduino board inside that 3D-printed enclosure. Hasty? Sure. Crude, or unpolished? Certainly. Worth selling? Well, that depends on the standards of the consumer. Nevertheless, those exact same critical engineers might also be kicking around ideas for their next Burning Man Persistence-of-Vision LED display–and guess what? It’s got an Arduino for brains! What may seem like hypocrisy is actually perfectly reasonable. In both cases, each designer is using Arduino for what it does best: abstracting away the gritty details so that designs can happen quickly. How? The magic (or not) of hardware abstraction.

Meet HAL, the Hardware-Abstraction Layer

In a world where “we just want to get things blinking,” Arduino has a few nifty out-of-the-box features that get us up-and-running quickly. Sure, development tools are cross-platform. Sure, programming happens over a convenient usb interface. None of these features, however, can rival Arduino’s greatest strength, the Hardware Abstraction Layer (HAL).

HAL is nothing new in the embedded world, but simply having one can make a world of difference, one that can enable both the artist and the embedded engineer to achieve the same end goal of both quickly and programmatically interacting with the physical world through a microcontroller. In Arduino, the HAL is nothing more than the collection of classes and function calls that overlay on top of the C++ programming language and, in a sense, “turn it into the Arduino programming language” (I know, there is no Arduino Language). If you’re curious as to how these functions are implemented, take a peek at the AVR directory in Arduino’s source code.

With a hardware abstraction layer, we don’t need to know the details about how our program’s function calls translate to various peripherals available on the Uno’s ATMEGA328p chip. We don’t need to know how data was received when Serial.available() is true. We don’t “need to know” if Wire.begin() is using 7-bit addressing or 10-bit addressing for slave devices. The copious amounts of setup needed to make these high-level calls possible is already taken care of for us through the HAL. The result? We save time reading the chip’s datasheet, writing helper functions to enable chip features, and learning about unique characteristics and quirks of our microcontroller if we’re just trying to perform some simple interaction with the physical world.

Cross-Platform Compatibility

Teensy 3.2 keeps form factor but adds hardware features
Teensy 3.2 keeps form factor but adds on-chip hardware features compared to 3.1

There are some cases where the HAL starts to break down. Maybe the microcontroller doesn’t have the necessary hardware to simultaneously drive 16 servos while polling a serial port and decoding serial data. In some cases, we can solve this issue by switching Arduino platforms. Maybe we actually do need three serial ports instead of one (Teensy 3.2). Maybe we do need pulse-width-modulation (PWM) capability on every pin (Due). Because of the hardware abstraction layer, the rest of the source code can remain mostly unchanged although we may be switching chip architectures and even compilers in the process! Of course, in an environment where developing code for the target platform does matter, it doesn’t make sense to go to such efforts to write the general-purpose code that we see in Arduino, or even use Arduino in the first place if it doesn’t have the necessary features needed for the target end-goal. Nevertheless, for producing an end-to-end solution where “the outcome matters but the road to getting there does not,” writing Arduino code saves time if the target hardware needs to change before getting to that end goal.

HAL’s drawbacks

arduino-serial-buffer-sizeOf course, there’s also a price to pay for such nice things like speedy development-time using the HAL, and sometimes switching platforms won’t fix the problem. First off, reading the Arduino programming language documentation doesn’t tell us anything about the limitations of the hardware it’s running on. What happens, let’s say, if the Serial data keeps arriving but we don’t read it with Serial.read() until hundreds of bytes have been sent across? What happens if we do need to talk to an I2C device that mandates 10-bit addressing? Without reading the original source code, we don’t know the answers to these questions. Second, if we choose to use the functions given to us through the HAL, we’re limited by their implementation, that is, of course, unless we want to change the source code of the core libraries. It turns out that the Serial class implements a 64-byte ring buffer to hold onto the most recently received serial data. Is 64 bytes big enough for our application? Unless we change the core library source code, we’ll have to use their implementation.

Both of the limitations above involve understanding how the original HAL works and than changing it by changing the Arduino core library source code. Despite that freedom, most people don’t customize it! This odd fact is a testament to how well the core libraries were written to suit the needs of their target audience (artists) and, hence, Arduino garnered a large audience of users.

Pros of Bare-Metalspeak

digitalWrite takes a whopping 52-55 cycles to change pin direction! [image source]
digitalWrite takes a whopping 52-55 cycles to change pin direction! [image source]
Are there benefits to invoking the hardware directly? Absolutely. A few curious inquirers before us have measured the max pin-toggling frequency with digitalWrite to be on the order of ~100 KHz while manipulating the hardware directly results in a pin-toggling frequency of about 2 MHz, about 20 times faster. That said, is invoking the hardware directly worth it? Depends, but in many cases where tight timing isn’t a big deal and where the goal of a functional end-to-end system matters more than “how we got there,” then probably not! Of course, there are cases when tight timing does matter and an Arduino won’t make the cut, but in that case, it’s a job for the embedded engineer.

Use the HAL, Luke!

To achieve an end-to-end solution where the process of “how we got there” matters not, Arduino shines for many simple scenarios. Keep in mind that while the HAL keeps us from knowing too many details about our microcontroller that we’d otherwise find in the datasheet, I don’t proclaim that everyone throw out their datasheets from here on out. I am, however, a proponent of “knowing no more than you need to know to get the job done well.” If I’m trying to log some sensor data to a PC, and I discover I’ll be saving a few days reading a datasheet and configuring an SPI port because someone already wrote SPI.begin(), I’ll take an Arduino, please.

If you’ve rolled up your sleeves and pulled out an Arduino as your first option at work, we’d love to hear what uses you’ve come up with beyond the occasional side-project. Let us know in the comments below.


Filed under: Arduino Hacks, Hackaday Columns, tool hacks


  • Newsletter

    Sign up for the PlanetArduino Newsletter, which delivers the most popular articles via e-mail to your inbox every week. Just fill in the information below and submit.

  • Like Us on Facebook