Github project website

This is nothing new, but apparently not many Github users know about this feature and I’ve recently learnt an easy way to set it up.

But let’s step back for a second: what are Github pages?

it’s a web space granted to each Github user and project where you can publish anything related to the subject: users might decide to publish their curriculum/resume or contact information while a project might publish a nice looking documentation.

A good set of information is available via a mini site which already guides you through the setup process, so I’m not going to reproduce that here.

Briefly, for a project site, the site contents are going to be hosted withing the project git repository (it does make a lot of sense to me) whitin a dedicated branch gh-pages.

What I wish to share is the set of git commands you can use to setup an existing project to host a clean Github pages setup.

Within the project folder you want to run:

git checkout --orphan gh-pages
git reset
touch .gitignore
git add .gitignore
git commit -m "gh-pages setup"
git push -u --all

You will end up with an almost empty folder (don’t panic, your project is not gone!) apart for the empty .gitignore file.

The project is now displaying what is published on your project’s Github pages, which is nothing at start. You can easily switch between the project contents and the project website by using the git checkout command:

  • git checkout master re-populates your project folder with your project contents
  • git checkout gh-pages brings you back to project website editing

The nice part of the above sequence is the newly created gh-pages branch is not going to share anything with your code branch structure or, if you prefer, master is not a parent for gh-pages!

You can now populate the website with your content using your HTML5 or MarkDown skills, or you can use one of the readily available templates from Github to get a nice looking index.html page to start from.

Also, additional and advanced features are available for multi-page websites via Jekill, but that’s another story.

FlexiPower: the interview

Following the enthusiasm of my previous post, I wish to share an interview a good friend of mine gave to me the latest days of August for his own blog.

The original interview run in Italian, but here I’m posting an English translation: thank you Francesco for pushing me into learning Arduino! 🙂


Zeirus: Hi Roberto. Can you explain with few words what FlexiPower is and which use, us mortals, can do of it?

Roberto: Hi Francesco, I’ll be very glad to do so! FlexiPower is a tool thought for electronic enthusiasts, being newbies or advanced. It is a portable power supply providing two independent channels, both voltage and current controlled. It might seem a niche instrument, but it’s not: anybody playing with an Arduino or a Raspberry Pi, but also those very beyond that phase, know it is an important tool. Usually they are bench instruments, heavyweight, powered by mains e quite expensive, in the order of thousands euro. Normally a newbie would look for cheap Chinese clones, but those have important culprits and might be extremely dangerous.
I wanted to keep costs down in my project, but I didn’t want to sacrifice anything in terms of quality, so I went for an headless instrument, without a screen or any physical user interface, but a remote control via a smartphone and a WiFi connection, with the advantage FlexiPower can be remotely controlled from the other side of the world! Going for a smartphone also allowed me to introduce a feature only the most expensive versions of these tools provide: continous and prolonged logging of current output, and the ability to plot a diagram.

FlexiPower_00

Zeirus: Did you base FlexiPower on some already existing project? If so, what have you specifically added/tweaked to make it “better” than the original?

Roberto: Obviously I hardly copied from another project made by somebody much more experienced and knowledgeable on electronics than I am: Dave Jones, author of a popular electronics channel on YouTube, did publish multiple videos describing, step by step, his own project uSupply. From an end user perspective FlexiPower adds a second channel a completely drops the physical UI, originally consisting of two rotary encoders and an LCD screen. In reality I had to face multiple little and less little problems, many of which I wasn’t aware of until I broke my nose on them.

La schermata di settaggio con presets La schermata del canale #2

Zeirus: How many hours/days have you spent so far developing FlexiPower?

Roberto: To be honest I’m not sure I can quantify it. If you consider I first had to learn how to create such type of instruments… actually I’m not sure I’ve understood all the secrets. After  had to learn the details of the starting project, study each of its components and understand their characteristics. From that point I started to believe it would have been easy, after a few months I undestood how much I was wrong. I don’t think it’s a lie to say I did spend no less than 10 hours a week for the past 18 months working on FlexiPower. Clearly most of the time was during the weekend and holidays, for the greatest joy of my partner!

Zeirus: I can only imagine her Posso solo immaginare la gioia immeasurable joy!🙂
Do you believe your senior experience on the Java programming language has anyhow helped you? 

Roberto: No, I don’t think so, to say the truth. Micro controllers are commonly programmed in C and even the smartphone user interface has been developed as an hybrid application, so based on JavaScript…. I would say Java has little to do with the whole project, but my software developer background has definitely guided me toward the remote interface and, maybe toward a new perspective on those type of tools, with characteristics reserved to more expensive ones.

Zeirus: Which open-source softwares did you use to develop your project? Do you believe they are up to the task or is there still something missing?

Roberto: That’s truly an interesting question because I did try many EDA softwares (CAD dedicated to electronics) for this project, but many were under my expectations: rough, impractical or extremely limited. Then something turned around my opinion: almost a year ago, during the Rome Maker Faire, I met somebody from the company producing the market leader software, Altium. Clearly their top of the line product , you can easily imagine that, is priced comparable to a car, but they had recently released a free version of their software called CircuitMaker. The only real limitation is you have to share your creations.
As a truly convinced supporter of open source I couldn’t avoid a try and I was really impressed by the tool quality: no surprise they are the market leaders. Up to now I believe it’s the best free tool for creating electronic projects, way above the old classic tools like Eagle CAD!

CircuitMaker_Editor_Ubuntu_Wine

Zeirus: That’s great! It’s a pity CircuitMaker is not – yet – available on non Windows platforms (even if you can actually make it work in Ubuntu via Wine). Anyway, do you believe electronics nowadays is simpler than in the past? Let’s say twenty years ago? If yes, what do you envision for the new twenty years? 

Roberto: Absolutely! Arduino has turned the micro controllers and digital electronics into toy, accessible to practically anybody. Just follow an online tutorial and you’ll learn how to burn a few components and get addicted. I still remember when my older brother was learning PIC micro controllers, spending hours to program them to blink an LED using an UV lamp to erase the chip!

Now you can get the  same results with 5 lines of code, an USB connector and you don’t even have to know the principles of electronics. Sure, after burning to death a few LEDs you might start to learn you need a series resistor, but isn’t a pleasure to see those bright little bastards die into smoke?

Zeirus: With the exclusion of the merciless genocide perpetrated against “those bright little bastards”, would you know consider yourself a true maker, or do you still miss “something” to be one?

Roberto: Everybody decides to build something starting from little or nothing can consider himself a maker, in my opinion. I believe I became a maker when i built my first LED cube, a miniscule 3 x 3 x 3 still sitting on my office desk which I’m really proud of!

perfboard

Zeirus: What is the tool you still miss in your maker “lab”?

Roberto: I don’t know where to start. To be honest my lab is contained inside 3 drawers of my home desk, including all the electrical components collected so far, the numerous boards and a certain amount of prototypes.

I don’t have much space in my house as I don’t own a garage or a room dedicated to myself only, so anything I use must hidden to sight when not in use (Zeirus’ note: that means hidden to his partner’ eyes! 🙂) . I own a little oscilloscope, with ridiculous characteristics, but adequate to my current needs. A multimeter, pen style soldering iron, a set of tweezers and screwdrivers, a caliper and little more. A tool I am aiming for is a CNC milling machine to quickly realize PCBs for my prototypes…

Zeirus: I know FlexiPower is going to participate as best project of the year on Circuit Maker and the competition will close in a few days! Are you near project completion? What is still missing?

Roberto: In reality it’s Project Of The Summer 2016, a competition closing by the end of August for which I spent a lot of time to refine FlexiPower. The project is at a really good stage, I just sent out an order for the second round of PCBs (10) as the first ones were unusable: I have made some mistakes, it was my very first time… I already have the components to build 4 prototypes of the FlexiPower, even if I believe a couple of tries to realize the next round of improvements.
The software is only in a very alfa status at this stage, but that’s not my top concern as that is my daily bread. I’m more concerned about the PCBs, I hope I didn’t made any other silly mistake this round: I obviously underestimated the complexity in such task and I wasted a lot of time in trial and errors… but I believe I’m there now!

Zeirus: Well, as we say: practice beats theory!😉 … The final question! Be honest: do you believe your project is a first place one?🙂

Roberto: Sincerely I can’t evaluate that, but I threw in all my enthusiasm and energy so that others, more knowledgeable and experienced then me, might consider it worth for the competition.

I would be really praised to receive a recognition for my project, but that’s not the reason why FlexiPower exists. I hope it will become the most forked project, possibly with great contributions from the CircuitMaker community… and it’s in a good shape so far!

Zeirus: Wonderful! Than there’s nothing left other than wishing you the best for the final result!

Roberto: Thanks a million buddy!

Am I a Meta Maker™?

Yesterday has been a special day for me.

It started as any other day of my recent life, with a late alarm after a too short sleep. As usual I had my morning shower and rushed into the office were I spent my day working together with the other members of my team and running meetings with my partners abroad: a day as many others, as I said.

It was quite late when I finally returned home, but I knew my day was not over yet: an electronics project is waiting on my desk, expecting somebody to troubleshoot the issue currently preventing the I2C bus communication.

I have spent countless nights working around this project, with great joy for my partner!

It all started because I wanted something compact to power my electronic projects, an hobby that caught me unarmed a couple of years ago, may be three.

Now I have this splendid (to my eyes) circuit board on my desk: a couple of plastic arms keep it suspended, while few wires depart from it to reach diagnostic interfaces, in an attempt to provide the information I’m seeking for.

In July and August my work on this project got an impressive boost: I decided to enter the CircuitMaker Project of the Summer 2016 contest.

img-about.png

I knew there were many, and much more experienced, people going to participate, but I wanted to be part of the game nonetheless: you need to test you abilities to know where you stand and you can improve.

Obviously, I must admit, I had hopes when I threw myself into the competition: I really wished to win the prize, that precision CNC looked so cool! Not to mention it’s a tool I would definitely wish! But before competition closing I had a look at the top projects and they looked so amazing…

maxresdefault

Well, I don’t stand a chance, but it was the opportunity to finish the project! I won already! Now I just have to solve this damn I2C issue…

So, yesterday I received an email…. The email contained a link to a blog post… but my name wasn’t in there. That didn’t surprise me much, I thought

Hey, look how cool are the runner up projects! I wasn’t even aware of that one…

There was also a YouTube video embedded in the post, so to discover my project was among the finalists! (Hey Ben, click on this link, please! smiley-10225)

Really? Did you really took my project into consideration for the final? Is it really so cool?

That was exactly my thinking while I was getting excited, now calling in my partner to join me and share with her the news.

 

Can you imagine my reaction when we got close to the end just to discover the big suprise? Well, something like…
celebrate.gif

Can you imagine how good it feels to get a recognition for your hobby, the thing you do just because you like to do it? And suddenly somebody tells you Well done buddy, this is really good!

It is just amazing guys, really amazing!

I wish to say Thanks! to all those who voted my project on the CircuitMaker community: you have been the ones who pushed me into the competition in first place!

Also I wish to Thanks! Dave Jones, the author of the uSupply, the design the FlexiPower is based on: you have thought me, you have inspired me and I know I have just made a few modifications to a great design!

I wish to say Thanks! to you guys at CircuitMaker for your great tool, it really feels great working with it: I finally feel like I have a professional EDA in my hands and the community and support is just great! Keep going lads, you are doing great!

Obviously I wish to say Thanks! to the young pretty lady from Othermachine Co, Danielle Applestone, for selecting FlexiPower as winner: I swear I didn’t bribe her!

Finally, but certainly not least, I wish to say Thanks! to my family and friends, who supported me along the route, with a special mention to Annamaria (my partner) who had to go in bed alone, in the cold winter nights of Central Italy (?!?!), so many times, while I was chasing my maker dreams sitting at my desk…

Thank you!
Thank you so much!

thank-you

Programming an ATmega328

Ever heard about Barebone Arduino? It consists of trimming down an Arduino to it’s very basic parts and can be really effective in cost reduction.

3197918087_c578d8c12f

Tipical Barebone Arduino

Even it might seem the simplest version of an Arduino (actually I wouldn’t be calling it an Arduino any more) we can go even further and drop the external crystal in favor of the internal (yes, there is one) oscillator: that is now just a plain ATmega328:

328pb_rev1_pinout

Thanks to pighixxx for his beautiful pinout diagrams!

To program an ATmega328 or, for what matters, many other MCUs, you can use an USBasp, an hardware device providing direct access to the MCU via ICSP, aka a programmer. Installing the USBasp drivers under Windows 10 has been time consuming, but luckily a very simple solution does exist.

I’m not going into the details of how you connect the USBasp to the ATmega328 as this is information widely available on the web and the first link is quite comprehensive in this regards. So the remaining part is, obviously, software!

There is only one option in my mind when it comes down to programming microcontrollers: Sloeber (formerly known as Arduino Eclipse Plugin). The latest release is just great and not only because I did personally contribute a few bits here and there, but because the whole thing is just a leap step forward in MCU development compared to Arduino IDE.

Programming a bare ATmega328 though has provided some challenges I’m here to describe for those who might encounter the same issues.

Installing the tools

With Sloeber it’s quite easy to install support for new boards, even those which are not built-in or, if you prefer, third-party.

Just open Window > Preferences > Arduino > Locations, you’ll find a link in the bottom part of the settings page, click on it and search the web page for the board or board set you’d like to install. I was looking for “barebone” and that is what I added into my list of locations: https://raw.githubusercontent.com/carlosefr/atmega/master/package_carlosefr_atmega_index.json (if you want to shortcut and avoid the issues I’ve faced, an alternative URL is available at the very bottom of this article).

locations

Then switch to the Platforms and Boards section to select and obtain the definitions to build for a bare ATmega328: obviously I’m going for the latest available version.

platforms

After a few seconds I got my Sloeber ready for compiling what would be a normal Arduino project but targeted at a barebone Arduino!

build config

My choice was to create a custom build configuration, but that’s totally optional.

Filling the gaps

I encountered a few compilation problems though, which I was able to overcome with some support.

Making the long story short I had to modify the JSON file associate to the Barebones ATmega Chips in order to provide some missing information:

  • the tools section, originally consisting of an empty array, should contain the references to the two tools used by the package, avr-gcc and avrdude
  • the toolDependencies section needs to be updated in order to match the tool versions now being linked

I’ve prepared a fixed JSON package file available from https://raw.githubusercontent.com/rlogiacco/arduino-eclipse-plugin/packages/package_atmega_index.json.

Also I had to copy the programmers.txt from arduinoPlugin\packages\arduino\hardware\avr\1.6.13 to arduinoPlugin\packages\atmega\hardware\avr\1.3.0 in order to make the USBasp protocol available with the new boards file.

Setting the fuses

When you buy a plain ATmega328 micro controller you are more than probably going to get the chip configured to the factory settings, meaning it will run at a 1MHz with it’s internal oscillator. That’s obviously a very conservative setting on which you have control, along with some other settings, via the chip fuses.

If you never had to deal with chip fuses before and the AVR ones in particular, you might want to read at least an introductory explanation  before going to change any of them.
WARNING: an erroneous setting of the chip fuses can turn your micro controller into a desk decoration, don’t blame me if that occurs to you!

I want the chip to run at 8MHz which requires just one bit to be changed, but I’m taking the opportunity to also tweak other parts of the settings and I’m going to use a nice AVR Fuses Calculator web application to do so:

  • low fuse 0xE2 means “use the internal 8MHz clock source and run at full speed
  • high fuse 0xD6 means “don’t clear the EEPROM each time and don’t reserve any space for a bootloader
  • extended fuse 0x07 means “don’t auto reset on min voltage

To do so I’m using the avrdude tool, which I already got installed automatically by Sloeber.

To quickly get to avrdude look at the last command printed by Sloeber into the upload console when you try to upload any firmware/sketch to the micro: it should look like the following

Launching X:\Sloeber\arduinoPlugin\tools\arduino\avrdude\6.0.1-arduino5/bin/avrdude -CX:\Sloeber\arduinoPlugin\tools\arduino\avrdude\6.0.1-arduino5/etc/avrdude.conf -patmega328p -cusbasp -Pusb -Uflash:w:D:\Projects\.cpp\Serial/Release/Serial.hex:i

The bold part is what you want to copy past into a command prompt and then add the missing bits:

X:\Sloeber\arduinoPlugin\tools\arduino\avrdude\6.0.1-arduino5/bin/avrdude -CX:\Sloeber\arduinoPlugin\tools\arduino\avrdude\6.0.1-arduino5/etc/avrdude.conf -patmega328p -c usbasp -U lfuse:w:0xE2:m -U hfuse:w:0xD6:m -U efuse:w:0x07:m

If all goes well you should get a nice and reassuring confirmation message like the following:

avrdude: safemode: Fuses OK (H:07, E:D6, L:E2)
avrdude done. Thank you.

Upload a firmware

Once you have all of the above in place, uploading a firmware to your micro controller is not going to be different from doing the same on any of your Arduino boards: hit the upload button, let Sloeber compile your code and enjoy your cheap and very professional setup!

USBasp & Windows 10

 

If you have an USBasp programmer and a recent Windows machine you have more than probably stumbled into a disappointing message, either from Arduino IDE or Sloeber:

avrdude: error: could not find USB device with vid=0x16c0 pid=0x5dc vendor='www.fischl.de' product='USBasp'

I believe I’ve spent at least a couple of hours searching for a solution which would not require downloading some weird drivers from an unknown source.

Almost all forum threads I’ve been reading were describing a clunky process which involved rebooting the OS and disabling the driver signature verification to permit the installation of a driver you could download from Mediafire or attached to the posts… not something I’m really willing to do.

Making the long story short you just download Zadiq (a well known, reliable and open source software) and install the libusbK driver for your USBasp device: that’s it!

usbasp

Markdown with Yada Wiki and Jetpack

In the office we have recently decide to migrate our team wiki to WordPress and Yada Wiki has been selected.

The team is also quite comfortable with Markdown, even if not everybody is ready to adopt it as the main editor, so I struggled a bit to find a solution, until I stumbled upon Jetpack.

I installed Jetpack directly from the WordPress admin console (which I just love!), but I had to connect to the server console to force Jetpack into developer mode, which is required if your server isn’t going to be publicly accessible.
To do so you need to open your wp-config.php, search for define('WP_DEBUG', false); and add the following line

add_filter( 'jetpack_development_mode', '__return_true' );

That brings you one step forward, but after enabling the Markdown feature in the Jetpack installation page you will be able to use Markdown in pages and posts only: your wiki pages will not be affected. That’s because Yada Wiki uses it’s own custom content type to distinguish wiki pages from other contents, which is a good thing.
So you need to extend the Markdown support to this additional content type, which is easily achievable adding the following lines at the very end of the functions.php file of your theme of choice:

add_action('init', 'my_custom_init');
function my_custom_init() {
    add_post_type_support( 'yada_wiki', 'wpcom-markdown' );
}

Now your wiki editors can decide to use the WYSIWYG editor or switch to the text editor and start typing their contents in Markdown syntax and preview their edits by just hitting the Preview button.

Win 10 FTDIgate solved!

My recent upgrade to Windows 10 has brought back to me an old issue: FTDI drivers.

Yes, I’ve bought cheap Chinese Arduino clones, mostly small boards to use in my projects as the official ones are quite expensive.

I never had problems on my previous Windows 7 install: even if I knew I was probably using one or more of those infamous FTDI counterfeited usb-to-ttl chips, I was lucky enough to dodge the FTDIgate.

When today, while setting up again my Eclipse + Arduino Eclipse Plugin, I stumbled into a weird message on the serial console my first thought was they did it again!

So, if your cheap Arduino clone has suddenly stopped responding and your OS is Windows 8, 8.1 or 10 you are probably stumbling on my exact same issue and you might want to carefully read this post to solve your troubles.

1. Assess

First of all you want to verify you are affected by the new FTDIgate, so connect via a serial terminal of your choice to your problematic Arduino: if you see a repeated message stating NON GENUINE DEVICE FOUND! then welcome aboard!

2. The tools

We will download all the tools we need upfront because this process implies we will have to disconnect from the Internet at a certain point to prevent Windows 10 to kick our butts with its automatic updates.

What you need is:

  • an older version of the FTDI drivers, latest working ones are 2.10.00, which you can get from FTDI in the No Longer Supported section (get the zip version)
  • a tool called CDMUninstaller which completely removes the existing drivers and it’s distributed by FTDI itself

3. Clean up

First we need to remove the drivers causing us all these troubles. If you believe you can do that via the Windows Device manager then youa re wrong: these drivers come in two separate parts, only one of which can be managed via the default driver management tool. You need the CDMUninstaller tool to ensure the drivers are completely removed:

remove

I’m not 100% it is needed, but I suggest you restart your system now, just to be sure there are no leftovers.

4. Prepare

It’s now time to load the new drivers, but be sure to do it with your Arduino board unconnected and while being offline.

Start decompressing the drivers package, then install the drivers right clicking on the two .inf files and selecting Install from the context menu.

Now it’s a good time to verify you have solved your problem, so open a serial terminal and check you can now communicate again with your Arduino.

The drivers we have just installed are going to be replaced at first opportunity by Windows with the trouble-making ones. In order to prevent Windows to find a more recent drivers version online, which will occur as soon as you’ll go back online, you have to open the two .inf files in any text editor, change the DriverVer line with a date very far in the future (I sat mine to 01/27/2034) and save.

If you now right click on the two .inf files and select Install from the context menu you’ll receive an error message informing you the files do not match their signature: don’t worry, we are going to solve this little issue.

We need to restart our OS, but allowing for unsigned drivers install: this can be achieved only with a system restart so open the Settings app and navigate to Update & security > Recovery.

Since the next step will actually restart your computer you have to read the next paragraph carefully before selecting the Restart Now button in the Advanced startup section.

5. Advanced Restart

Once in the Advanced restart section you’ll have to browse the advanced settings to Disable drivers signature verification, something a little tricky to achieve, but look at the following pictures and prepare yourself:

656x307ximage49-pagespeed-gpjpjwpjjsrjrprwricpmd-ic-cwzcnv7v-_

Select option Troubleshoot

656x307ximage50-pagespeed-gpjpjwpjjsrjrprwricpmd-ic-s7_14-sqwn

Head into Advanced Options

656x307ximage51-pagespeed-gpjpjwpjjsrjrprwricpmd-ic-izel4o6a5

Pick the Startup Settings

656x307ximage52-pagespeed-gpjpjwpjjsrjrprwricpmd-ic-mfl_b-m4mc

And finally Restart

656x473ximage53-pagespeed-gpjpjwpjjsrjrprwricpmd-ic-m7oxusdlqr

Activate the Disable driver signature enforcement setting

During the restart process you will be asked to select an option to activate during the next boot: we need to disable drivers signature verification, which was option number 7 for me.

6. Permanent Install

After reboot you will be able to right click on the two .inf files and select Install from the context menu: you will still receive a warning, but this time you will be able to get around the issue and proceed ignoring the verification error.

You can now go back online on the Internet, this time Windows shouldn’t be able to replace your working drivers!

7. Verify

It’s now time to restart your computer and verify everything still works. After a reboot open the Device Manager, select the problematic Arduino COM port and check the drivers version: if it’s anything above the version you selected…. well, something went wrong.

If I were you would try restarting from step 1, but this time try to read more carefully the instructions!

Cucumber is NOT a testing framework!

I have been repeating this statement over and over on the Cucumber forum, but apparently with no good result. To me this is a simple statement and I fail to understand what’s difficult to understand in its simplicity: Cucumber (JVM, Ruby, C, the flavour doesn’t matter) is not a testing framework.

I’ll try to further explain the statement, not because I believe it needs to be explained, but hoping an explanation will solve doubts. To do that I’ll try to state the facts in way as much practical as I can.

JUnit, TestNG and DBUnit are examples of a testing framework: they provide facilities to put a software in a certain condition, leverage some parts of the software and assert the outcome responds to the expected parameters.

The goal of those frameworks is to provide the tools to achieve the result (testing the software) with the least possible effort and the maximum outcome. As such, they have programming structures for asserting conditions are met, for setting up the test rig and tear down the test rig as well, ensuring the system is always in a clean condition before a new test is run.

Cucumber doesn’t have any of those facilities, simply because it is not a testing framework.

Cucumber is a specifications tool, something completely different. It uses Gherkin (the language) to describe in a natural language the software specifications.

Does anyone of you remember the Use Case Template? use-case-template-visio

Well a Cucumber feature is much more like one of those than a bunch of tests, would you agree?

There was once a time when we were describing software systems by collecting a few of those use case templates in a Word document, right?

Now, it wasn’t much of a trouble to describe a system like that, at least at first instance, but after a couple of maintenance cycles the above documents were not describing the system any more: I haven’t found one single situation where the above documents were maintained and kept in sync with the implementation. So the system documentation was just obsolete after a few months of operation.

Why was that? Because the cost of maintaining such documentation was not justified by the short term benefit of doing so: why should I spend 30 minutes to find the correct place where to apply the patch in the system documentation if the fix itself costs me 15 minutes?

So, Cucumber steps in and tries to transform the above specifications into something valuable and alive. How?

The specification format (or structure, if you prefer) is almost free, so to leave the writer the freedom to express himself freely. This is even less structured than the template above, but there are good practices telling us how to maximize the result, like providing the list of actors and the general goal at the very beginning.

The file is plain text, so to avoid any requirement on the tool used to open and modify the document and doesn’t add any formatting to avoid reader to be distracted or writer being dragged into endless make it prettier sessions.

A file represents a use case (feature in the Gherkin language), so you end up having multiple files, each one representing a piece of the software. This greatly simplifies version management, collaboration and merging, enabling multiple writers and revisors working on a single system. It’s not uncommon to use the same version control system in use for the system to store the documentation.

Files can be structured in a hierarchical fashion via folder structure, so big systems with lots of features can organize their specifications.

Files can be annotated via tags so to create parallel organizational structures, with the folder structure still being the prominent one: this enables additional categorizations, useful to track other associations between use cases (features), as much as what the introductory Use Case Diagram was doing in the Word document.

What makes the biggest confusion, though, is Gherkin files can be executed.

That is what Cucumber provides: the support software structures and an execution environment for Gherkin files.

Why? To create a connection between the system documentation and the documented system, so to ensure the documentation is aligned to the system it describes.

How? By mapping each statement in each scenario with some lines of code in the language you like (Ruby? C++? Java? Scala?). If the code ensures somehow the system does what it is expected to do, than the documentation is in sync with the implementation.

Only this last part resembles a test. Only at this stage there is some code involved. And usually testing frameworks and automation libraries are used to do such verification, like JUnit and Selenium.

So, if you need to test your system, please use a testing framework! If, instead, you want to document your system, you are welcome to use Gherkin and Cucumber!

nRF24 walk through – Sensors’ firmware

Let’s move to the 3rd part of the nRF24 walk through series before the excitement cools off, shall we?

Now that I have three boards wired and I’m certain only my code can break things up, it is time to create the sensors’ firmware.

It should be quite simple: all we need to do is getting the transceiver set up at the beginning and send the current sensor identifier every time the button is pressed.

As this series is intended to be a tutorial, I’ll expand a little on the basic requirement. To add a bit of salt on our sensors’ network communication, we will expect the hub to send back to the nodes 2 pieces of information in response to their click events:

  • the total count of clicks received from all nodes is going to be part of this article and we’ll achieve that using the ack packet payload
  • the number of clicks received from the specific node will be instead added in another post, so not to push too much info in one shot

Each device is going to require a unique identifier: as radio network address (think ofit like an IP address) and for the software to print out (like a computer name). I will use one byte stored in EEPROM for both: this will limit the maximum amount of sensors for this network to 255 (0 is going to be reserved as the hub identifier/address).

That’s not such a low number after all, but we want our hub to print out the node identifier as a letter, so I will further limit the range to [1, 26] to simplify the hub code.

NOTE The above limits to the number of nodes is very soft and has been introduced into this tutorial to simplify the code. The real hard limit to the number of unique nodes is much higher and in the order of 1 thousand billions (1 followed by 12 zeros)!

Setting things up

The radio transceiver configuration occurs, as you might expect, in the setup() function, plus a global variable declaration and a few defines:

// Creates a new instance using SPI plus pins 9 and 10
RF24 radio(9, 10);

// nRF24 address family: all addresses will be in the format 0xFACEC0DE## with the last two
// bytes determined by the node identifier.
#define ADDR_FAMILY 0xFACEC0DE00LL
#define MAX_ID_VALUE 26

#define BUTTON_PIN 3

// This node unique identifier: 0 is used for the hub, anything above MAX_ID_VALUE is considered
// not valid
byte nodeId = 255;

void setup() {
  SERIAL_DEBUG_SETUP(57600);

  // Setup the push button
  pinMode(BUTTON_PIN, INPUT_PULLUP);

  // Read the address from EEPROM
  byte reading = EEPROM.read(EEPROM_ADDR);

  // If it is in a valid range for node addresses, it is our address
  if (reading > 0 && reading <= MAX_ID_VALUE) {
    nodeId = reading;
    DEBUG("Node identifier is %c", nodeId + 64);

    // Initialize the transceiver
    radio.begin();
    radio.setAutoAck(true); // Enables auto ack: this is true by default, but better to be explicit
    radio.enableAckPayload(); // Enables payload in ack packets
    radio.setRetries(1, 15); // Sets 15 retries, each every 0.5ms, useful with ack payload
    radio.setPayloadSize(2); // Sets the payload size to 2 bytes
    radio.setDataRate(RF24_2MBPS); // Sets fastest data rate, useful with ack payload

    // Opens the first input pipe on this node address
    radio.openReadingPipe(1, ADDR_FAMILY + nodeId);

    // Opens the first input pipe on this node address
    radio.openReadingPipe(2, ADDR_FAMILY + 254);
#if (SERIAL_DEBUG)
    // Prints current configuration on serial
    radio.printDetails();
#endif
  } else {
    DEBUG("Invalid node id %u found: use S## (a number between 1 and %u) to configure the board", reading, MAX_ID_VALUE);
  }
}

There are a few details in the code related to the nRF24 module which might be valuable to explain:

  • when I instantiate the module driver class I’m specifying only two out of the five pins used by module (not including the power line) because the MISO, MOSI and SCK pins are defined by the board SPI interface
  • I’m defining a network address class 40 bits long (0xFACEC0DE00), not very different from IP addressing when you specify the network class (192.168.0.0 is the network class C of an host having IP address 192.168.0.*)
  • I’m enabling auto acknowledge packets (useful to know if your transmission was successful) capable to carry payloads (more on this later)
  • I’m instructing the library to auto retry packet transmission every half millisecond (500 us) up to 15 times, so to reduce transmission errors
  • I’m setting a fixed payload size, which improves transmission reliability, of 2 bytes
  • the data rate is set to highest possible value (2Mb per second), so to have the ack packets coming back in time for being recognized (more on this in the next article)
  • one of the input pipes (the second if we count in pipe 0) is set to this node address. This is not used to receive ack packets (pipe 0 is used for that), but it will come into play later on, when I’ll show how the sensors can receive data (other than ack packets) from the hub (or whoever wants to talk to us, for what it matters!)

IMPORTANT Reading pipes are not associated to addresses you talk to, but to addresses you want to listen for. If that sounds confusing, consider reading pipes like mailboxes: you can have multiple mailboxes, but that does not limit who can send you mail, actually anybody knowing at least one of them can.

This means you are not limited to receive data from maximum five nodes (as commonly and mistakenly known) and this walk through will demonstrate it!

NOTE If you want to know more about pipes and addressing, the best source of information is the datasheet, but to summarize:

  • you have one writing pipe only, but you can change it’s value to whatever address you want to talk to
  • there are six reading pipes, only two (0 and 1) can be associated with 40 bits addresses, with pipe 0 automatically associated to the writing address (to receive acks); this means pipes 1 to 5 share the same upper 32 bits, but you can change the reading pipes addresses
  • almost every address is valid, only a few are excluded (like 0x0000000000, 0xFFFFFFFFFF and similar)
  • address length is configurable to 40 (default), 32 or 24 bits, but the limitation on pipes 1 to 5 still applies as they keep sharing the upper 24 or 16 bits

For the sensors’ setup() function to complete correctly we need to read a valid node id from EEPROM which means we have to push something in the correct location: this is responsibility of another function called config(). I’m not going to analyze that function in detail, but it should be clear its purpose is to allow to set the node id using a serial connection.

A looping life

Moving into the sensor loop() function, the plan is even easier, if possible: check the button state and, if pressed, send the sensor node identifier to the hub.

To add value to this tutorial we will expect the hub to send back the total amount of received clicks and we will use ack packet as the carrier of this information.

NOTE Acknowledge (here abbreviated into ack) packets are used to verify data transmission has been successful. This is a common technique used in TCP/IP protocol as well: if you don’t feel comfortable with the concept just consider those as return receipts.

The protocol used by this chip allows to optionally attach some information to the return receipts: we refer to this info as the ack packet payload.

Ack packets maximum payload size depends on data rate and re-transmission speed and is explained in details in the nRF24 datasheet at paragraph 7.5.2.

I’m going to use some macros to perform a simple software debouncing on the push button, but apart from that, the code should be very easy to read:

// Button debouncing macros
#define DEBOUNCE 15
#define DMASK ((uint16_t)(1<<DEBOUNCE)-1)
#define DF (1<<(uint16_t)(DEBOUNCE-1))

// Macro for detection of falling edge and debouncing
#define DFE(signal, state) ((state=((state<<1)|(signal&1))&DMASK)==DF)

// Button debouncing status store
unsigned int buttonStatus;

void loop() {
  // Checks if we are trying to configure the node identifier
  config();

  delay(1); // Slow down a bit the MCU

  // Checks the push button: if we enter here the button has been pressed
  if (DFE(digitalRead(BUTTON_PIN), buttonStatus)) {

    // Sets the destination address for transmitted packets to the hub address
    radio.openWritingPipe(ADDR_FAMILY);

    // Put transceiver in transmit mode
    radio.stopListening();

    // Transmit this node id to the hub
    bool write = radio.write(&nodeId, 1);

    DEBUG("Send attempt from node %c was %s", nodeId + 64, write ? "successful" : "UNSUCCESSFUL");

    // Get acknowledge packet payload from the hub
    while (write && radio.available()) {
      unsigned int count;
      radio.read(&count, 2);

      // This function shows how a node can receive data from the hub
      // without using ack packets payload
      receiveNodeCount();

      DEBUG("Got response from hub: total click count is %u", count);
    }
  }
}

Once again, let’s analyze in detail the parts specific to the nRF24 module, which are activated whenever the push button state has gone LOW for enough time:

  • I set the transmission destination address using the openWritingPipe() function, providing the hub node identifier (that is the node we want to send data to)
  • to put the module into transmit mode we need to call the stopListening() function
  • since ack packets have been enabled, we can transmit reliably, so the result of the write() function (a boolean value) is going to be stored and checked
  • the data I’m going to transmit (the sensor node identifier, stored into the nodeId global variable) is provided to the write() function along with the number of bytes (only one) we are going to send. The actual payload sent on the air is going to be 2 bytes long, because we have set the packet size to a fixed value of 2, which means the packet will be zero filled
  • if the transmission was successful we expect to have an ack packet available. We have enabled ack packets payload, so we can pull out an unsigned int (2 bytes) into the count variable: this represents the total amount of clicks the hub has received so far

This is a complete example of data exchange, but the fact we are using the ack packet payload has some caveats we will analyze when we will talk about the hub.

The whole picture

The complete sensor’s firmware is available on Github and its compilation requires the two libraries mentioned in the previous post: the RF24 lib from TMRh20 and my own MicroDebug lib.

Please ignore the receiveNodeCount() function call and its implementation for now: we’ll get into that in another post. If you prefer, comment out line 105 to completely exclude that part of the firmware.

Naming the newborns

To avoid packet transmission conflicts we will have to initialize each sensor board with its own unique identifier: that’s the part handled into the config() function.

Internally I will use numeric identifiers, but they will be translated into one character when printing, hence the limit to numerical values between 1 and 26: that’s the number of letters in the latin charset.

Each board will initially have 255 as identifier, which is to be considered invalid, but you can change it via serial.

Once connected, type the S character followed by the board identifier you want to assign (like S2 or s5): the board will print the corresponding identifier as a character, store it in EEPROM and self reconfigure.

IMPORTANT The communication relies entirely on assigned node identifiers. The hub has no other way than the node identifier to distinguish between the nodes.

If you configure two nodes with the same identifier they will be considered as one and their clicks will not be distinguished. You can leverage this in some situations and have two sensors appear as one, if that’s what you want.

Sensor node id configuration is very simple and can be done via serial console in a handful of seconds

Sensor node id configuration is very simple and can be done via serial console in a handful of seconds

Repeat the procedure on each board and you have your sensors setup!

From this point forward your sensors does not require to be hooked up to your computer, they will just need power. If you have enough USB ports available and decide to leave the sensors connected to your computer though, you will be able to receive some debug messages on the serial ports and enjoy the occurring communication… once we have the hub running!

eclipse-console

The Arduino Eclipse Plugin supports multiple consoles and distinguishes among them using different colors: black text is from the hub, red, blue and green from the sensors!