10 Things To Do After Obtaining Your Amateur Radio Technician License

I recently passed the Technician exam and for the last few weeks have been having a lot of fun getting on the air, learning about digital modes and even tracking satellites.  It took about 1 week for my call sign (KD2GNX) to be posted online.   This post documents 10 things to do after you pass the Technician exam that will make the hobby more enjoyable and will help you get involved in different communication modes with a very small financial investment.

  1. Get an email Address with your Call Sign
    Providing your email to the contacts you make is a common occurrence.  An email in the format of your-call-sign@emailprovider.com is easy to transmit since call signs will be exchanged early in the conversation.
  2. Learn the Phonetic Alphabet
    Not knowing the phonetic alphabet gives away your novice status and makes communication more difficult.  Spend a couple of afternoons learning the phonetic alphabet or print a cheat sheet and have it close to your radio.
  3. Join a Ham Radio Club
    There is a great deal of knowledge about communications in local ham clubs.  Even if you do not have an outgoing personality, you can join a club, attend meetings and start learning  about the different topics ham clubs present.  Most clubs have a one time membership fee or very low membership fees in order to keep up with maintenance of repeaters.
  4. Subscribe to Ham Radio Podcasts
    Check http://arvideonews.com/hrn/ for a list of different sites presenting ham radio content.  You can play these shows while doing yard work or while driving and get a good deal of information to keep you up to date with the latest news in the hobby.
  5. Get the General License
    Put together a 3 month plan to get the General license.  Besides the additional privileges provided by the General license, your will get more information on FCC rules and augment your knowledge about communication.
  6. Invest in a Cheap Handheld Radio.
    My first Radio was a Baofeng GT-3 with an enhanced Nagoya 771 antenna.  With an investment of US$60 for the radio and US$14 for the antenna,  I am able to access repeaters in my area, track the International Space Station (ISS) and other satellites, use repeaters connected to WIRES, EchoLink, IRLP, etc. and monitor Fire, Ambulance and Police frequencies.  The experience you get with these different communication modes, will help you solidify the requirements for your next radio.
  7. Drive Around with your Handheld Radio
    You will be amazed at the amount of radio traffic you pick up while driving around.  I used CHIRP to program in my handheld radio all repeaters and emergency service frequencies I can find from my house to work.  After a few days you will identify which repeaters have traffic during commute hours, which ones have nets, etc. Using CHIRP is an efficient way to quickly change your radio frequencies to track repeaters in the areas you will be visiting.
  8. Get an EchoLink Account – Embrace Voice Over IP (VOIP)
    There are multiple VOIP/Radio modes such as EchoLink, WIRES, IRLP, DSTAR, etc.  EchoLink provides clients for Windows, Linux, IOS and Android that allow you to communicate with people all over the world using your computer/tablet/phone as a radio.  Once you understand how EchoLink works, it is easy to understand how the other modes work.  Embrace the marriage between Radio and VOIP and you will be able to experiment setting up your own gateways or reach out other hams from any location that has internet access.  I was in the Caribbean recently and using my iPad and the WIFI signal from the hotel I could communicate with other hams in Argentina, England and Florida while drinking Mojitos by the pool.
  9. Get into Software Defined Radio
    With a small investment of US$10 – US$20 you can configure a software defined receiver capable of receiving continuously between 25MHz-1700MHz (range varies depending models).  With a SDR dongle and a program like SDRSharp you will be able to monitor multiple bands and get a visual representation of the communication spectrum in your area.  Depending on your computer capabilities you can add multiple dongles and launch multiple instances of SDRSharp.  Visit the RTL-SDR site for a crash course on Software Defined Radio.
  10. Monitor Digital Traffic
    Once you have configured an SDR dongle, you can listen to other hams, police, fire, ambulance and Taxis.  You can even configure a SDRSharp plug-in to use the receiver as a scanner.  In addition you can decode different type of digital traffic.  By using a program such as Virtual Cable or VB-Cable (free), you can feed the audio output from SDRSharp into programs like PDW to decode pager traffic.  I am able to decode traffic from a hospital that is less than a mile from my house, as well as traffic from taxis and what appears to be my local Target store which is about 2 miles from my house.  Besides pager traffic you can also monitor AIS (Automatic Identification System) for ships and Automatic dependent surveillance-broadcast (ADS-B) for aircraft.  The software and dongle can be installed in a laptop and provide additional listening capabilities while you are on the road.

With a small investment of about US$100 you can get exposure to a wide range of communication modes and learn a great deal about ham radio.  In the process you will hopefully make a few new friends.

 

Arduino Template Express – Compiling Core Libraries

I remember spending countless hours compiling the Linux kernel back in my college days.  That experience helped me develop a taste for command line utilities and the productivity they bring to a developer workflow.  As you expand your horizons experimenting with AVR micro-controllers and Arduino boards, the time will come when you will need to compile the Arduino core libraries for a new or existing board.   The reasons could range from experimenting with a board at different frequencies to using other Atmel micro-controllers. This post covers how to add a new development board to the Arduino Template Express environment and then compile the libraries it supports.  This post is part of the Arduino Template Express (ATE) series. You may also be interested in these other posts:

  1. Arduino Template Express – Installation
  2. Arduino Template Express – Creating a Sketch
  3. Arduino Template Express – Creating a Library
  4. Arduino Template Express – Using ATTiny Micro-Controllers

Prerequisite

In order to follow this tutorial you will need to have installed Arduino Template Express (ATE).  You will also need msbuild installed and available in your application path together with a few add-ons.   To install ATE follow the Arduino Template Express – Installation.  Atmel Studio 6.1 is based on Microsoft Visual Studio. My expectation is msbuild 4.0 is installed with Atmel Studio when it installs the dotnet framework, but I cannot verify that is the case because I had Microsoft Visual Studio already installed when I installed Atmel Studio. To check if msbuild is installed open a command window and type the following command.

reg.exe query "HKLM\SOFTWARE\Microsoft\MSBuild\ToolsVersions\4.0" /v MSBuildToolsPath

If reg.exe comes back with unable to find the specified registry key or value, msbuild is not installed.  You will need to download the full Dotnet Framework 4.0 from Microsoft.  You will also need to install the msbuild community task and the msbuild extension pack.

Registering the New Board

Figure 1 contains a list of the libraries and boards supported by  Arduino Template Express (ATE).  For the purpose of this tutorial, I am going to add support for the Arduino Mega 1280 board.

List of supported libraries

Figure 1 – Supported Libraries

The task of compiling core libraries for a new board requires registration of the board in the boards.xml file and registering a reference to the new board in the project for each library you want compile.  Let’s take care of registering the Mega1280 board first.  Since the Mega2560 and the Mega1280 are very similar boards, I am going to use the entry for the Mega2560 as a model.  Follow these instructions:

  1. Locate the directory where ATE is installed.  Typically USER\Documents\Arduino Template Express.  If you are not sure open a command window and type set | find “ATE_HOME”.  It will display the environment variable ATE_HOME which points to the location where ATE is installed.
  2. Open %ATE_HOME%\boards.xml with your favorite editor.  Copy the <BoardList> entry for the Mega2560.  In the original file it begins on line 51 and ends on line 71.
  3. Paste the entry and make the changes illustrated in listing 1.   I have used the description of the board provided in the Arduino site.
    <BoardList Include="Mega1280" >
        <Processor>ATmega1280</Processor>
        <Location>Mega1280</Location>
        <Variant>mega</Variant>
        <Vid>null</Vid>
        <Pid>null</Pid>
        <SkipFrequencies></SkipFrequencies>
        <SkipLibs></SkipLibs>
        <DefaultProgrammer>Mega1280BootLoader</DefaultProgrammer>
        <EnableForProjects>true</EnableForProjects>
        <EnableForLibCompilation>true</EnableForLibCompilation>
        <DefaultSpeed>16</DefaultSpeed>
        <BitmapName>external.mega1280</BitmapName>
        <DataPort>COM5</DataPort> <!-- Use the port supported in your environment -->
       <SupportedFrequencies>16</SupportedFrequencies>
       <Description>
       The Arduino Mega is a microcontroller board based on the ATmega1280 (datasheet).
       It has 54 digital input/output pins (of which 14 can be used as PWM outputs),
       16 analog inputs, 4 UARTs (hardware serial ports), a 16 MHz crystal oscillator,
       a USB connection, a power jack, an ICSP header, and a reset button.
       It contains everything needed to support the microcontroller; simply connect it
       to a computer with a USB cable or power it with a AC-to-DC adapter or battery
       to get started. The Mega is compatible with most shields designed for the
       Arduino Duemilanove or Diecimila.
       </Description>
     </BoardList>

Note that for the graphic that is displayed with the board when the new project wizard is launched I have specified external.mega1280.  This tells the wizard to look in the %ATE_HOME%\Graphics for a file named external.mega1280.png.  The size of the picture must be 150×150 pixels and the format must be png.  Figure 2, illustrates the picture of the board used.  Save it to %ATE_HOME%\Graphics and make sure it is named external.mega1280.png.

Mega1280 Board Figure 2 – Mega1280 Board

Next step is to take care of the default programmer for the Mega1280.  I declare Mega1280BootLoader to be default programmer.  A development board can be configured to support multiple programmers (bootloader,ISP,custom,etc) and the desired programmer activated from the sketch project.  Search for Mega2560BootLoader.  It should be around line 471.  Copy the content from line 471 to line 480 and paste it..  Listing 2, illustrates how the programmer entry should be changed.

   <Programmer Include="Mega1280BootLoader">
        <ComPort>COM5</ComPort> <!-- Use the port supported in your environment -->
        <Protocol>wiring</Protocol>
        <ComPortSpeed>115200</ComPortSpeed>
        <ProgTransfer>avrdude</ProgTransfer>
        <Verbosity>-v</Verbosity>
        <MiscParams></MiscParams>
        <SupportEEPROMTransfer>false</SupportEEPROMTransfer>
        <Comment></Comment>
    </Programmer>

Change the ComPort entry as needed in your environment.  The Programmer entry in listing 2 uses avrdude and the wiring protocol to program the board.  You could also use an ISP programmer if you are not going to use the bootloader.  When the option to upload a sketch is pressed in Atmel Studio, this is the entry that drives how the sketch is uploaded to the development board.  We are now ready to add the Mega1280 board to the Arduino core libraries to complete the process.

Adding the New Board to Target Libraries

The first library we are going to test is the ArduinoCore library.  Open the project %ATE_HOME%\Source\ArduinoCore\ArduinoCore.atsln.  Next open the file Scripts\TagetBoards.xml.  The TargetBoards.xml contains a list of all the boards supported by the ArduinoCore library.  When compiling all supported boards from the command line, the build script loops through the list of supported boards and makes each supported board the active board, changes variables and references according to each board profile and compiles the code.  Finally the compiled code is copied to the %ATE_HOME%\Source\_Stage\BoardName\Libs\Frequency.  Follow these steps to take care of the changes.

  1. Create an entry for a new supported board and name it Mega1280 (the name must match the name used in the boards.xml).  Use the default programmer (Mega1280BootLoader)  and frequencies configure in boards.xml.
  2. Modify the CurrentBoard entry (first one in the file) to also reference the Mega1280 development board.  This step is very important.  By making the Mega1280 the CurrentBoard, the core library will only be compiled for the Mega1280 when you invoke the MakeIt.bat script with the Compile parameter.  If you skip this step, you will need to call MakeIt.bat with the CompileAll parameter which will take a while since the code will be compiled for all boards and it will get to the Mega1280 based on its position in the list.  See Figure 3 for an illustration of how the beginning of the TargetBoards.xml file should look like after the changes are done.  Do not delete the list of all the other boards supported.  We are done with the changes, let’s go ahead and compile the code.
Target Board Registry

Figure 3 – TargetBoard.xml

Compiling Arduino Core

There is a “feature” of msbuild that prevents the scripts distributed with ATE 1.0.2 Beta 3 from running when there are spaces in the path.  I have a fix that will take care of this in the final ATE 1.0.2 release.  If you have ATE 1.0.2 Beta 3, copy the folder %ATE_HOME%\Source to the root of your C:\ drive, you will end up with a c:\source folder.  If you have a folder name source already in your c:\ drive you can provide any name you want as long as it does not have a space.  Follow these instructions:

  1. Open a command window.  All prerequisites discussed at the beginning of the post need to be met for the rest of the instructions to work.
  2. Go to the directory source\ArduinoCore\Scripts and type makeit compile.  This will compile only the current board, which we previously setup to be the Mega1280.  See Figure 4 for results of compilation.

    ArduinoCore Compilation Result

    Figure 4 – Result of ArduinoCore compilation

  3. After compilation is completed, check the directory source\_stage.  You will find a Mega1280 directory with sub-directories name Headers and Libs.  The Headers contains all headers files for the ArduinoCore and future libraries you compile for this board.  The Libs contains a sub-directory for every supported frequency for the board.  In this case 16 (representing 16mhz) is the only directory available.  Inside the 16 directory you will find the ArduinoCore libraries in release and debug modes.  See Figure 5.

    stage folder

    Figure 5 – Stage folder after compilation

  4. Invoking the script makeit compileall will compile the ArduinoCore libraries for ALL boards supported.  This takes a long while and IS NOT required for this tutorial.
  5. The last step requires copying the Mega1280 folder just created to the %ATE_HOME%\Boards folder.  This is the root folders from where Atmel Studio projects pickup libraries for linking sketches.  For instance, when you develop a sketch for the Mega1280 board, libraries are expected to be found at %ATE_HOME%\Boards\Mega1280\Libs\16 and headers are located at %ATE_HOME%\Boards\Mega1280\Headers.  The frequency at the end of the libs directory changes according to the value of the F_CPU variable.
  6. To compile other libraries repeat the steps documented in the above section Adding New Board to Target Libraries.  In fact you can just copy the <CurrentBoard> and <SupportedBoard> entries created for the ArduinoCore library, see figure 3, and paste it into the targetboards.xml of the library you want to compile.  Then go to the source\LibraryIWantToComile\Scripts and run makeit.bat compile.  Look in the source\_stage\Mega1280\Libs\16 and you will find the debug and release versions of the compiled library.

Configuring a new board takes is a bit involved the first time you do it since you will need to configure tools, paths, etc. After you get the environment setup correctly and understand the mechanics of adding new boards and configuring projects to support it, adding future boards will take you a few minutes.

Arduino Template Express – Using the ATTiny Micro-Controllers

Featured

The Arduino core libraries provide a well defined structure for developing code with the different micro-contollers it supports, but not every project requires the power provided by the ATMega 328 or 2560 chips. Simple projects can take advantage of the ATTiny family of micro-controllers. The goal of this post is to demonstrate how to use Arduino Template Express (ATE) to deploy the Arduino Core libraries to the ATTiny family of micro-controllers. This post will show you how to setup a development board with the ATTiny85 micro-controller and enable it with serial communication capabilities and the ability to use the Arduino Core libraries. In order to follow this tutorial, you will need the following:

  1. Atmel Studio 6.1 or greater
  2. Arduino Template Express (ATE) 1.0.2 or greater
  3. An ISP programmer – I will use AVRISP-MKII and AVR Dragon to demonstrate deploying code with either programmer. If you have an Arduino based ATTiny programmer, that is also fine.
  4. FTDI Breakout Board – The FTDI Basic Breakout from SparkFun or the FTDI Friend + extras from Adafruit will do the job. I will use FTDI Basic Breakout from SparkFun to allow the ATTiny85 to send serial information to a terminal. If you are creative and do not have access to a FTDI Breakout board, you can remove the ATMega328 chip from an Uno board and use the serial communication capabilities already included in the board as a substitute for the FTDI Breakout board.
  5. An ATTiny85 assembled on a breadboard or from a development board such as the one provided by Tinkerlog.

Although, I will use an ATTiny85, the instructions applies to any of the ATTiny micro-controller for which ATE provides a compiled Arduino core library. Figure 1, contains a list of supported micro-controllers.

List of supported libraries

Figure 1 – List of Supported Libraries and micro-controllers

Hardware Configuration

Let’s begin by configuring the development board. Figure 2, contains the schematic diagram of the minimum configuration needed to run an ATTiny85. This configuration uses the internal 8 MHZ clock to drive the micro-controller. In order to transfer data to the FTDI breakout board, pin 2 of the micro-controller is connected to the TX pin of the FTDI breakout board. The 5V supplied by the FTDI breakout board on pin 3 provide power to the micro-controller.  Jumper JP1 is used to enable/disable resetting the micro-controller when a terminal connection is made to the FTDI breakout board.  Jumper JP1 should be open when using the AVR Dragon to debug sketches.  If connected, the capacitor C3 causes side effects while stepping through the code.  By the way, having this jumper on the original Uno board would be a welcome feature.   Note the CTS pin of the FTDI breakout board is connected to ground to prevent the FTDI chip from stopping the transmission.

Figure 2 - ATTINY85 Breadboard Diagram

Figure 2 – ATTINY85 Breadboard Diagram

Figure 3 contains a breadboard implementation of the design. Note the usage of breadboard helpers to speed up the assembly of the circuit.

ATTiny85 Breadboard Implemenation

Figure 3 – ATTiny85 Breadboard Implementation

The FTDI breakout board comes in 5V and 3.3V flavors.  Breakout boards with more advance features have a jumper that controls the voltage output and can be switched between 3.3V and 5V.  If you happen to have a 3.3V FTDI breakout board, you will need to introduce an external power supply to drive the circuit.  Figure 4 contains a circuit diagram that uses an external power supply to provide power to the micro-controller.  Note the 3.3V pin of the FTDI breakout board is not connected to the micro-controller.

Figure 4 - ATTINY85 Breadboard diagram with dedicated power source

Figure 4 – ATTINY85 Breadboard diagram with dedicated power source

The circuits illustrated in figure 2 and 4 are functionally equivalent, the only difference is how the micro-controller is powered. It is important to note that in order for the ISP programmer to work, the micro-controller needs to be connected to an independent power source. Both, the 5V provided by the FTDI breakout board or an external power supply will satisfy this requirement.  Before proceeding connect the ISP programmer to the ISP header (J1) and configure the micro-controller fuses. Table 1 contains a list of the values of the different fuses that need to be programmed.

ATTINY85 Fuses

FuseValue
SELFPRGEN[ ]
RSTDISBL[ ]
DWEN[ ]
SPIEN[X]
WDTON[ ]
EESAVE[ ]
BODLEVELDISABLED
CKDIV8[ ]
CKOUT[ ]
SUT_CKSELINTRCOSC_8MHZ_6CK_14CK_64MS
EXTENDED0xFF (valid)
HIGH0xDF (valid)
LOW0xE2 (valid)
ATTINY85 Fuses configuration to run using internal clock oscillator at 8MHZ.
If you need information abut AVR fuses check Lady Ada tutorial on her site. Figure 5 illustrates the Atmel Studio screen from where the fuses are programmed. See (Tools/Device Programming) or (Ctrl+Shift+P).

Figure 5 - ATTINY85 Fuses as seen by Atmel Studio

Figure 5 – ATTINY85 Fuses as seen by Atmel Studio

At this point we have a development board assembled in a breadboard. The following step is to register the board in Arduino Template Express so the wizard can pick it up when new projects are created.

How ATE Supports Multiple Boards

ATE uses the concept of a development board as an abstraction of the environment for which a developer creates code. Figure 6, illustrates an entity diagram of a development board.

ATE Entity Diagram

Figure 6 – ATE Entity Diagram

Each development board has a series of properties that identify the board.  A programmer is is a logical construct that includes the port used to program the board and the application responsible for transferring the sketch created by a developer.   ATE comes configured with 17 defined boards, 8 of which can be activated during installation. An activated board shows in the list of available boards when the wizard runs to create a new project. ATE supports an unlimited number of boards that can be manually added or activated after installation. In order to enable the board ArduinoTiny85 follow the following instructions:

  1. Open the file boards.xml with your favorite editor. I would recommend Notepad++ if you do not have a favorite editor already.
  2. Find the board “ArduinoTiny85″, around line 247
  3. Change the property <EnableForProjects> to true, it is false by default. This is the flag that tells the ATE wizard to include the board as an option.
  4. Change the programmer to AVRDRAGONISP-AT.  Since I am using AVR Dragon and will use the ISP header and the atprogram.exe provided by Atmel.  If you are using another programmer, find a suitable entry or create one.  Figure 7 illustrates a modified record.
  5. Configure the DataPort field to reflect the Com Port that is created when you connect the FTDI Breakout Board.  Check the Device Manager list of Com Ports if necessary.
  6. Last, locate the programmer entry AVRDRAGONISP-AT and make sure the ComPort property is set to avrdragon and the protocol to ISP.  ATE 1.0.2 beta was shipped with the wrong port/protocol combination.  This will be changed in the final release.
Editing boards.xml

Figure 7 – Editing boards.xml

At this point we have a development board configured and registered.  Let’s proceed to create a hello world sketch.

Creating Hello World

Start by launching Atmel Studio, selecting new project, and select Arduino Sketch, see figure 8.  Once you press OK the ATE Wizard will start.

atmel-new-project

Figure 8 – New Project Dialog

 Figure 9 illustrate what the wizard will show you.  The boards will vary based on what you have installed, but the ArduinoTiny85 should be in the list.  Select ArduinoTiny85 and also select 8 Mhz from the supported speed drop down.  Press OK and a new project will be created tailored to the Attiny85.

ate-wizard-arduinotiny85

Figure 9 – ATE Wizard with Attiny85 Board

Compile the program and you will get two errors and 4 warnings.  The errors are related to the fact the Arduino Serial library is not supported by the ATTiny85, that’s OK, let’s get rid off all Serial references and concentrate first on making the LED blink.  We’ll introduce a Serial library replacement later.  Comment all lines referencing Serial in main.cpp and Utility\buildinfo.cpp.  Do not delete the lines, just comment them.  At this point you should be able to compile the code and receive 4 warnings, but the code will compile successfully.  Make sure your board has power and the programmer is connected to the ISP header.  Press Deploy in Atmel Studio and see the LED start flashing.  If this the LED does not flash, retrace your steps to verify everything is connected properly.  It is important to note the code is Arduino friendly and you can move to any Ardunio board for which the core libraries are compiled.  This means you are capitalizing on your investment to learn and use the Arduino core library.  Now the LED is flashing and the code can be successfully deployed, let’s take care of the Serial connection.

Enabling Serial Connection

The TinyDebugSerial library provided as open source by Rowdy Dog Software is an implementation compatible with the Serial library provided by Arduino.  It only uses one pin to transmit and does not provide data receive capabilities.  Download TinyDebugSerial.cpp, TinyDebugSerial.h, TinyDebugSerial9600.cpp and core_build_options.h.  Include the “TinyDebugSerial.h” in main.cpp and “..\TinyDebugSerial.h” in BuildInfo.cpp.  Remember to remove the comments on the lines of code referencing Serial.  Recompile and deploy the code.  Open a terminal and connect to the proper COM Port and you will see output coming from the Attiny85.  If you do not want to deal with all of this, a fully functional sketch is included in the link below.  Download, compile and deploy.  If you have configured the ArduinoAttiny85 properly in your board, the deployment script will pick all your local parameters and deploy successfully.

Download Source Code: Sketch85

Arduino Template Express – Creating a Library

In previous posts I discussed How to Install Arduino Template Express and How to Create a Sketch.  In this post let’s discuss how to create a library using Arduino Template Express and what are the advantages and disadvantages of partitioning your code into libraries.  Let’s go!

Divide and Conquer

In order to understand the benefits of libraries, let’s begin by creating the same hello world sketch we created in the How to Create a Sketch post.  Follow those instructions and come back when you have a working sketch in place. Let’s take a look at the main.cpp file to discuss what is going on in the sketch.  See Listing 1.

#ifndef SKETCH_H_
#include "Sketch.h"
#endif
/* Running counter */
static unsigned long counter = 0;
//#pragma message "Sketch Running At: " XSTR(F_CPU) " HZ"
void setup()
{
/* Setup pin connected to board LED for output */
pinMode(LED, OUTPUT);
/* Initialize serial interface */
Serial.begin(SERIAL_SPEED);
/* Show build information via serial interface */
#if defined(ENABLE_TEXT_MESSAGE)
ShowBuildInfo();
#endif
}
void loop()
{
digitalWrite(LED, HIGH);
delay(DELAY_LENGTH);
digitalWrite(LED, LOW);
delay(DELAY_LENGTH);
Serial.print(MESSAGE);
Serial.println( ++counter );
}

Listing 1 – Hello World Sketch

This is a monolithic sketch.  Everything it does is packed into one single development unit.  The sketch uses the Serial library and functions from the core Arduino library, but the functionality of flashing the LED and sending notifications via the UART are packaged in a single program.  As the code stands it is truly a one developer job and contains the following structural (not functional) deficiencies.

  • Unit Testing this code is very difficult.  At best you will be able to verify the LED goes on an off, but testing for LED initial conditions and controlling the timer is very difficult.
  • Having multiple developers work in this program is not possible.  Everything is packed into a single unit of work (main.cpp).
  • Reusing any code of value you develop in this sketch is not possible.  At best you will be able to use clipboard inheritance (copy and paste for the object oriented challenged).
  • Replacing the on board LED by an external LED driven from a II2C/SPI chip requires a great deal of changes because main.cpp is operating too close to the metal by invoking digitatWrite directly.

Let’s visualize how a library can help with our design by introducing a layer of abstraction.  If this was production code, I would make sure there is also a layer of abstraction for the serial communication and for the timer.  For the purpose of this example I will concentrate on the LED.  The sketch main job is manipulating the state (ON|OFF) of a pin by calling digitalWrite().  Let’s introduce the concept of a Led class with two functions on and off.  Figure 1 illustrates the class diagram of the ILed interface and possible implementations.

class-diagram-led

Figure 1

Programming to the ILed interface allows swapping different implementation transparently at compile or run time.  Instead of calling digitalWrite directly the sketch will invoke ILed.on() or ILed.off() to turn the LED on or off.  What are the advantages and disadvantages of introducing this level of abstraction?  I am glad you asked.  Let’s start with the advantages.

  • Programming to an interface promotes code reuse and in this case allows the design of the sketch to evolve to support an Led directly attached to the micro controller or attached to an external component with which the micro controller can communicate.  Besides SPI or II2C you could turn on and off an LED via a XBee,  WiFi, or radio interface.  The possibilities are multiple as long as you implement the ILed interface.
  • Unit Testing an ILed implementation is possible and independent of the main code.  Once an implementation is tested it can be shared and reuse in binary form with a high degree of confidence.  This promotes good design practices such as the Open/Closed principle.
  • Multiple developers can work now on this sketch.  One in the main.cpp sketch and the others in the implementation of the Led, SPILed, II2CLed classes.  The developer responsible for main.cpp will integrate to the different implementation as they become available.  The size of this sketch does not warrant such a division of labor, but in a the context of a bigger project, this option is a plus.
  • The code becomes more cohesive, a desirable trait, this benefits a few “ilities” such as maintainability, reliability, reusability, and understandability.  See Cohesion Metrics for Predicting Maintainability of Service-Oriented Software and Software Design Metrics for Predicting Maintainability of Service-Oriented Software.

Not all is good news, the introduction of ILed in the code has the following disadvantages:

  • After introducing ILed and the Led implementation, the size of the sketch is bigger.  The introduction of abstract classes (the interface of the class diagram) carries a virtual table that takes more memory than the direct digitalWrite approach.  In fact according to avr-size, the primary memory usage of the release version of the sketch goes from 3,176 bytes (9.7%) to 3,676 bytes (11.2%), while the data usage goes from 267 bytes (13%) to 296 bytes (14.5%).  This increment in size is not related to using a library, but to the introduction of ILed into the design.
  • The solution is more complex.  There are more moving parts and more code to develop in order to provide an abstraction layer for the LED.

Let’s refactor the code to introduce a library.  To add a library project to the solution, right-click on the solution and select add/project.  The new project dialog appears.  See Figure 2.  Select Arduino Library Wizard, provide the name Led and select the default location to save it.  Follow the wizard and select the same development board you previously selected for the sketch.  This will create a new library project named Led in your existing solution.

add-new-project-dlg-with-lib-selected

Figure 2 – Adding new library

You can download the full solution with the sketch and the library at the end of the post.  All paths for the sketch to find the library have been added using relative paths.  This is a manual step that I expected Atmel Studio to take care of when I added the library as a reference to the sketch, but unfortunately it did not happen.  See Listing 2 for the new sketch code.

#include

/* Running counter */
static unsigned long counter = 0;

/* Micro-controller connected LED */
Led led;

/***************************************************
Return LED as ILed to isolate caller from what
type of ILed is used
****************************************************/
ILed* getLed()
{
	return &led;
}

 void setup()
 {
	 /* Initialize LED */
	 led.Init(LED);

	 /* Initialize serial interface */
	 Serial.begin(SERIAL_SPEED);

	 /* Show build information via serial interface */
#if defined(ENABLE_TEXT_MESSAGE)
	ShowBuildInfo();
#endif

 }

 void loop()
 {
	 getLed()->On();
	 delay(DELAY_LENGTH);
	 getLed()->Off();
	 delay(DELAY_LENGTH);
	 Serial.print(MESSAGE);
	 Serial.println( ++counter );
 }
 

Listing 2 – Hello World Sketch with ILed

Line 35 and 37 take care of turning the LED on and off.  Reading the code makes it clear you are dealing with an LED.  I could have created a global ILed pointer and initialize it during setup(). The getLed() function provides an opportunity for putting logic that may switch at run time the type of LED the sketch controls.  The source code for the solution with both projects can be downloaded from here.

For Arduino developers making the transition to Atmel Studio, I hope this post has given you an introduction to how to use libraries in your projects. Coming from the Arduino IDE, an environment that promotes code reuse as source code, hides the true advantages of using libraries to decouple functional areas of an application.

Arduino Template Express – Creating a Sketch

In this post we’ll go over creating a sketch with Arduino Template Express.  I assume you have followed the instructions of how to install ATE from my previous post.  Launch Atmel Studio and select File\New\Project or Ctrl-Shift-N.

atmel-new-project

Select Arduino Sketch Wizard, give it a proper name and location and hit OK.  The wizard will be launched with the list of development boards you have configured during installation  or after installation by modifying the boards.xml file.

ate-wizard

I will use the Uno board for this example.  Pick an appropriate board from your setup and hit OK.  Atmel Studio will render a new project with the following layout.

ate-solution-explorer

This sketch flashes the on board LED and sends a running counter via the serial port.  Compile the sketch and  take a look at the output window.

ate-output

The sketch is compiled and as part of the compilation the template keeps track of how many successful and failed compilations have taken place.  It also keeps track of how many successful/failed deployments occur.  Let’s deploy this puppy.  Select Tool\Deploy or press deploy in the tool bar if you have it configured.  The output window should display the outcome of the deployment.  If you launch a terminal window and connect it to your development board data port, you will see a running counter every time the LED flashes.

Additional Goodies Included Provided by ATE

  • Take a look at Utility\BuildDate.cpp.  This file gets rebuilt every time the sketch is compiled.  It generates the time stamp of the last build and you can store it in ram, EEMEM or PROGMEM.  You can optionally use this information by calling GetBuildDate().
  • Utility\BuildInfo.cpp has ShowBuildInfo() to output build information to the Serial port.
  • Utility\BuildNumber.cpp keeps track of how many successful deployments has been made.  You can optionally use this information to keep track of your deployments.

That’s all for now.  In my next post we will go over creating libraries with ATE.

Arduino Template Express – Installation

The Arduino ecosystem consist of an IDE, development boards, development libraries and a vibrant and engaging community involved in the support and expansion of all of the components that make the ecosystem.  I acknowledge the pedagogical benefits of the Arduino IDE but if you are already used to Atmel Studio, the Arduino IDE feels like developing with training wheels.  The Arduino Template Express (ATE) enables Atmel Studio to create sketches using Arduino libraries and development boards.  AVR developers can take the best of the Arduino and continue using Atmel Studio and all the benefits it provides.  This post will walk you through the installation of ATE.

Arduino Template Express Configuration

In order to install ATE you must have already installed Atmel Studio 6.1 and Arduino 1.0.4 or higher.  Both of these programs must be installed and running successfully.  Download ATE from the Arduino Template Express site at CodePlex.  Before running setup make sure you close all instances of Atmel Studio that may be running, run atesetup.exe and agree to let the program run with administrative rights.  The following screens will guide you to the setup process.  As of the writing of this post version 1.0.2 (Beta 3) is available for download.

ate-screen1

Press Next to get to the next screen

ate-screen2

Press “I Agree” to accept the license and move to the next screen.

ate-screen3

The atesetup.exe program will install pre-compiled Arduino libraries, project templates and a wizard to drive the initial configuration of sketches.  Click Next to continue.

ate-screen4

This screen let’s you select the directories where Atmel Studio accepts new templates and the location where you want to store the application.  It is advisable to install it in your documents\Arduino Template Express folder.  The installer will try to pre-populate the directories for you.  Click Next to continue

ate-screen5

The following screen will attempt selects the location of AVRDUDE and its configuration file also the path for atprogram.exe distributed with Atmel Studio.  Note that as of Atmel Studio 6.1 the path of atprogram.exe has changes and now it is under the atbackend directory.  The installer will try to find these programs for you, but if does not, you will need to provide their paths before continuing.  Press Next to continue.

ate-screen6

The Board Selection screen allows you to select up to 8 boards you already own.  Do not worry, if you have more than 8 boards.  After the installation is completed you can add as many boards as you want to the boards.xml file.  In my case I have 3 development boards, an Uno, Mega2560 and Leonardo.  Note the Leonardo board requires two different ports, one for data and the other for programming.  Once you have defined all your boards, press Next to continue.

ate-screen7

The External Tool configuration configures the option to deploy sketches from within Atmel Studio. The option is configured in the Tools menu and it is recommended that you configure the Deploy option as part of one of the tool bars in order to enable one click deployment.  Your screen may be a little different depending on the number of external tools you may have already installed in Atmel Studio.  Click Next to continue.

ate-screen8

The About to Install screen gives you a list of what is going to be installed.  Click Install to continue and after a little while the end of the installation screen will show giving you the option to launch the readme file or go to the web site to get additional information.  I suggest you take a quick look at the readme file.

ate-screen9

That’s all.  Hit close and the installation is completed.  If you forget where is the program installed, open a command window and type set | find “ATE_HOME” to find the path where the ATE was installed.  Next post I will walk you through the generation of a sketch that blinks the on board LED and uses the serial port.

Arduino Programming Using Atmel Studio 6.0

This article is no longer relevant.  Please follow the Arduino Template Express update to find a more mature offering to allow development of Arduino sketches in Atmel Studio 6.1.

The Arduino IDE is a good development environment to get started with microcontrollers.  It holds your hand and hides complexities that get in a novice way.  As you gain experience and want to use advance features such as refactoring, assembly language or binary libraries, working with the Arduino IDE just doesn’t cut it.  Moving to a more advance IDE is the next logical step for a mature Arduino user.  It is the equivalent of leaving your home to go to college. Jaycon Systems has a well written three part tutorial explaining how to configure Atmel Studio 6.0 to compile Arduino projects. I have taken a different approach to solve this problem and have created an installation script to accomplish the following;

  1. Distribute a binary file for the core library (libcore).
  2. Distribute binaries of the Arduino libraries (libEEprom, libEthernet, libFirmata, libLquidCrystal, libSD, libServo, libSoftwareSerial, libSPI, libStepper, libWire).
  3. Distribute a solution with projects for all the libraries specified above so libraries can be recompile and redeployed as needed.
  4. Distribute a project template for Arduino Sketch.  This allows you to do a new project and select Arduino Sketch from the list of available templates.
  5. Distribute a project template for Arduino Lib.  This allows you to do a new project and select Arduino Library from the list of available templates.
  6. Distribute a deployment scripts to write sketches to the destination chip.  This allows a one click deployment to the Arduino board.

The rest of this post covers the configuration of the installation script and the deployment scripts in the Atmel Studio environment.

Configuring Installation Script

In order to run the installation script, you need Arduino 1.0.1 or greater and Atmel Studio 6 or greater.  Both of these programs must be installed and running successfully.  The installation script is located at the Arduino Installer site at Codeplex.  It contains all the binaries and scripts required for the installation.  Follow these instructions carefully for a successful installation.

  1. Download the installation package from Codeplex
  2. Unzip in a directory of your choice.  For the purpose of this post I am going to assume you have decompressed the installation script at c:\arduino-install.
  3. Open the file c:\arduino-install\install.bat with your favorite text editor and go to the :SetUserVariables label, around line number 31
  4. By default the ATMEL_CPU is configured to ATmega328p, change this line if necessary to reflect your microcontroller.  Typical values are ATmega32u4 (Leonardo),  ATMega328p (Uno), ATmega2560 (Mega), ATmega168 (Diecimila).
  5. The CPU_FREQUENCY and ARDUINO_VERSION do not need to be changed.  I have tested with the  Arduino 1.0.1 IDE successfully with these default values CPU_FREQUENCY=16000000 and ARDUINO_VERSION=100
  6. Set the COM_PORT variable to the communication port you are using to communicate with the Arduino board.  The default is COM3.
  7. Set the COM_PORT_SPEED variable to the proper value if necessary.  The default is 115200.
  8. The VARIANT variable refers to the pin layout of the board.  Change it accordingly to reflect the type of board you have.  The values are standard (Uno, Diecimila), leonardo (Leonardo), etc.  The default value is standard.
  9. Last setup the AVRDUDE_ROOT_DIR variable with the value of the root director where the avrdude is located.  This could be done from the Arduino installation or from Winavr.  Note that the avrdude.exe would be at AVRDUDE_ROOT_DIR\bin\avrdude.exe from the path you specify.
  10. Save the file and open a command window.  Go to the directory c:\arduino-install and run install.bat.

After a few seconds you should see an output similar to that illustrated on Figure 1.  The installation script has done the following;

Installation Results

Figure 1 – Installation Results

  1. Create directory structures at C:\users\YOUR_USER_NAME\Documents\Atmel Studio\Libs and Headers.
  2. Under Libs there are three directories, ArduinoCore for the core library, Arduino for all the Arduino libraries and Public for your personal libraries.
  3. Under Headers there are three directories, ArduinoCore for the core library headers, Arduino for the different Arduino library headers and Public for your personal library headers.
  4. All binaries and header files have been deployed to these directories.
  5. There is a file named deploy.bat located at c:\users\YOUR_USER_NAME\Documents\Atmel Studio.  This file is responsible for performing generic solution and project name clean up and then invoking the localdeploy.bat file that is located in the Arduino project directory and is part of the sketch template.
  6. In the c:\users\YOUR_USER_NAME\Documents\Atmel Studio\Templates\ProjectTemplates there are two files.  Arduino Library.zip and Arduino Sketch.zip, these are the library and sketch templates for Atmel Studio.
  7. At c:\users\YOUR_USER_NAME\Documents\Atmel Studio\ArduinoLibrariesSource a solution named ArduinoLibraries.atsln has been deployed with the source code for all the Arduino libraries so you can recompile them from within Atmel Studio if you wish to update the distributed binary libraries.

Configuring Deployment Script

The configuration of the deployment script allows you to do deployment of Arduino sketches with one click or keyboard shortcut.  Sketches are deployed to the Arduino board while libraries are deployed to the Public folder of the library directory created by the installation script.  Follow these instructions to configure the deployment script in Atmel Studio;

  1. Open the External Tool manager from Tools/External Tools
  2. Setup a new entry named &Deploy with the characteristics illustrates in Figure 2.

    Deploy Tool Definition

    Figure 2 – External Tool Definition

  3. The & before the D, makes it a hot key while in the context of the Tools menu.  This means pressing ALT-T followed by D will launch the Deploy script.
  4. The parameters must be $(SolutionDir) $(ProjectDir) $(ProjectFileName).  There is a space between each parameter.
  5. Select use Output window so you can see the outcome of the deployment within Atmel Studio.
  6. The top most entry is External Tool 1, the second one is External Tool 2 and so on.  Moving the entries up or down changes the External Tool to the command located at the target position.  If you have multiple external commands registered, keep track of the position where Deploy is located because we are going to need it later.

Let’s create a custom toolbar and add some commands that will facilitate the development experience.

  1. Go to view\Toolbar\Customize and create a new toolbar.
  2. Name the toolbar Productivity.  Hit OK and make sure the checkbox is selected.

    Productivity Toolbar

    Figure 3 – Creating a Productivity toolbar

  3. Select the Commands tab and select the Toolbar radio button.
  4. In the drop down select the Productivity toolbar we just created.
  5. Add the command Build\Build Solution
  6. Add the command Tools\External Command1 (or whatever the name of the Deploy command is in your setup)
  7. Move it up and down as needed.

    Toolbar Commands

    Figure 4 – Toolbar Commands

  8. Click on the Keyboard button and select the Tools.ExternalCommand1
  9. Enter a shortcut for it and press Assign.  In my case I configured the Tools.ExternalCommand1, which is the Deploy script as CTRL+SHIFT+P

    External Tools Shortcut

    Figure 5 – External Tools Shortcut

  10. Hit OK and we are done.  You should see a toolbar with the following information.

    Deploy Toolbar

    Figure 6 – Productivity Toolbar

The option to deploy is available via a click on the Deploy button in the Productivity toolbar or via CTRL+T followed by D or via CTRL+SHIFT+P.  Any one of these three options should satisfy your workflow.

Creating Arduino Sketches

To create your first Arduino sketch in Atmel Studio 6, launch Atmel Studio, select File\New\Project.  The new project window appears similar to figure 7 with all the installed templates.

Atmel Studio New Project

Figure 7- Atmel Studio With Arduino Templates

Select Arduino Sketch, change the name to TestSketch1, change the location if necessary and press OK.  A new solution is created with a project named TestSketch1.  The project has three files, with the following content;

  1. main.cpp – contains code to blink the led on the Arduino board.  This is so you can have a quick block of functional code.
  2. localdeploy.bat – this is the local deployment script.  This file is called by the deploy.bat script located in your c:\users\your_user_name\Documents\Atmel Studio\deploy.bat.  It gives you the opportunity to customize deployment for a particular sketch.  The localdeploy.bat is ready to deploy the hex file located in the Release directory, not debug.  This script reflects the port, speed and directory information provided to the installation script.  I have submitted internal enhancement request AVRSV-3699 to Atmel to have the $(Configuration) variable exported to indicate you are running in Release or Debug mode.  Until this issue is addressed the default hex file deployed is the one in the release directory. You can change the script to deploy from the Debug directory if necessary.
  3. readme.txt – This file contains a list of the Arduino libraries, which files you need to include and which libraries you need to add to the linker.

Before compiling the code you need to open the project properties (ALT-F7),  select All Configurations and under Toolchain\AVR/GNU Linker\Libraries add libcore.  See Figure 8.  There is a bug in Atmel Studio 6 that does not include the libraries added to a project template.  I have submitted internal bug AVRSV-3701 to Atmel for this issue.  Note the Library search path is automatically populated with the directory structure where the libraries are located. After adding the library you can go ahead and compile the code, then press the deploy button in the Productivity Toolbar.  You will see avrdude copy the hex file to the Arduino board and the onboard LED start flashing.

Add Core Library

Figure 8 – Add Core Library

Creating Arduino Libraries

To create an Arduino library, select File\New\Project and select the Arduino Library template from the list of available templates.  Name the library TestLib1 and change the directory as necessary.   A new directory is created with four files.

  1. foo.h and foo.cpp contain a dummy class
  2. localdeploy.bat is the deployment script responsible for deploying the library and header files to the Public directory of the Lib and Header created during installation.  As before only the Release version is deployed for the same reasons previously stated.
  3. readme.txt contains a blank file.

If you need a reference to libcore in your library you must add it as explained for the sketch.  Deploying the library copies all the header files and *.a files to the Public directories.

Conclusion

Adopting Atmel Studio has the potential to increase your productivity and expose you to advance concepts such as mixed language programming (C/C++ and Assembly).  If you are a Microsoft developer familiar with Visual Studio, you will feel right at home in Atmel Studio 6.  Let me know if the script has been of assistance transitioning out of the Arduino IDE.

Capturing Your Project Vision

A hobby is by definition an activity done regularly in one’s leisure time for pleasure.  I am an electronic hobbyist and most of the electronic projects I work on come to fruition as the result of a learning experience.  Rarely, I get to identify a clear need and start working on a solution for it.  The incubation process is more like this; I find an interesting subject as a result of a magazine article, blog post or new product.  I work on a prove of concept to understand the subject and during this stage ideas come to mind where to apply the new concept.  This leads to the creation of a project and on weekends, I get to work on it until completion.  The approach to the creation of a personal project is significantly different from a commercial environment in which an idea must provide a financial or strategical advantage in order to become a project.  Independently of how you get to conceive new projects, they all require a vision.  The goal of the vision is to capture at a high level what is going to be done and who is the beneficiary.  The vision helps you, a team of one, to stay focus on the goals of the project and prevent you from going into the wilderness following new topics of interest that may come up while working on a project.  The purpose of this post is to discuss five different styles to capture a project’s vision. I have picked one project from my backlog to drive the discussion.  The project is a breadboard tool to assist electronic hobbyists in prototyping new projects.

Problem Statement Style

This style presents the vision of a project as a problem to be solved.  It identifies the affected parties and what is the solution the project provides to the problem.  Here is the vision expressed as a problem statement.

The problem of offloading away from the primary micro-controller the functionality to drive LCD displays, manage keypad input, emulate single/array of I2C devices, drive arrays of LEDs and manage arrays of seven segment displays while prototyping a new project on a breadboard affects advance and novice electronic hobbyists.  The impact of which is longer prototyping time, additional complexity, duplication of effort, abandoned projects and wasted time building one off components to support prototyping efforts.  The Breadboard Butler would address these problems by providing the following features; It would be released under a non viral open source/hardware license. It would be reprogrammable to support different type of services. It would provide services for driving LCD displays, keypad input, emulating I2C devices, driving LEDs and driving seven segment displays.  It would create an online repository where services could be shared between users.  It would run from a breadboard. It would use AVR technology. It would allow the primary micro-controller to access services using the I2C protocol to minimize the number of pins required for integration. It’s implementation cost would be less than $US 20.00.

Free Form Style

This style does not follow a particular template.  It allows you to tailor the vision to the project at hand.  Here is the vision expressed in free form style.

The goal of this project is to increase the productivity of electronic hobbysts when prototyping new projects on a breadboard by proving a solution with the following features; It would be released under a non viral open source/hardware license. It would be reprogrammable to support different type of services. It would provide services for driving LCD displays, keypad input, emulating I2C devices, driving LEDs and driving seven segment displays.  It would create an online repository where services could be shared between users.  It would run from a breadboard. It would use AVR technology. It would allow the primary micro-controller to access services using the I2C protocol to minimize the number of pins required for integration. It’s implementation cost would be less than $US 20.00.

Business Opportunity Style

This style has some similarities with the problems statement style.  Typically when expressing the vision as a business opportunity a contrast is drawn between the product to be developed and other products in the market.  It is important to be objective and professional when comparing your project with existing ones, specially if they are open source.  Trashing someone’s project to highlight features of your own is not a good practice and in my opinion takes away from the value of your vision.  Here is the vision expressed as a business opportunity;

For advance and novice electronic hobbyists who use any of the following techniques while prototyping a project on a breadboard; LCD displays, Alphanumeric keypads, I2C device simulation, array of LEDs and seven segment displays.  The Breadboard Butler is an open source programmable breadboard add-on that uses AVR technology to provide services to drive LEDs, control LCD displays, keypads or simulate I2C components to improve prototyping efficiency.  Unlike LCD backpack/driver boards using shift registers or GPIOs, the Breadboard Butler uses the I2C protocol to offloads all the processing complexity of providing a service to an independent micro-controller.  This allows the electronic hobbyist to concentrate on the scope of the prototype instead of wasting time building supporting infrastructure.

Product Box Style

This style allows you to present your vision as a finalized product.  The vision is documented on a product box to contribute to the illusion of a completed product.  The style of box you select is up to your imagination and the type of effect you wish to achieve.    Here is a Photoshop illustration of the vision as a product box.

Mind Map

It has been said that a picture is worth a thousand words.  This style allows you to present your vision in one single picture and categorize features as necessary.  How simple or complex you create your mind map is up to you and how receptive you are to graphical representations.  The mind map below was created with the open source application FreeMind.

Conclusion

I first learned about the problem statement and business opportunity styles around 1997 while using Requisite Pro a product part of the Rational Rose suite, this was before IBM bought Rational Rose and butchered it beyond recognition. Free Form and Product Box styles were picked up as part of different agile methodologies. The Mind Map style was recommended by a member of the AVR Freaks community.  Which style is best to document a project vision? There is not a correct answer to this question.  It depends on which format provides the most information to you or the audience that will read the vision.  The benefits of articulating a clear vision for your project go beyond helping you stay in scope.  If you release your project as open source, a well documented vision will also help future contributors understand short and long term goals of your project.

Downloads

HD44780 Protocol Analyzer

One of the best investments I have made recently has been on an 8 channel Saleae Logic analyzer.  The 16 channel unit was unfortunately outside of my budget.  The current version of the software that drives the logic analyzer is Logic 1.1.15.  It comes with multiple protocol analyzers for serial, parallel, I2C and others.  While integrating an LCD display based on the ubiquitous HD44780 to an ATTINY2313 microcontroller, I needed to debug the initialization sequence of the driver I was using.  Using the parallel protocol analyzer that comes with the Logic software can do the job, but requires painful analysis of each line and going back and forth to the data sheet to translate hex codes to commands.  As a result of this effort I have created a HD44780 protocol analyzer for the Saleae Logic/Logic 16 products.  The rest of this post documents the features of the protocol analyzer and how to install it and take it for a quick spin.

Analyzer Features

The HD44780 Protocol Analyzer supports three modes of analysis in order to balance the type of device you have (Logic or Logic 16) with the different programming modes of the HD44780.  The 11 bit mode, requires 8 channels for data and 3 channels for control.  This mode is only supported in the Logic16 device, since it requires 11 channels.  It analyzes communication with the HD44780 using 8 channels for data.

Figure 1 – 11 bit mode

The 8 bit mode, uses 3 channels for control and 5 channels to supports analysis of 8 channels of data.  In this mode the first 3 bits of the data byte are not captured.  It allows owners of the Logic (8 channels) device to operate in virtual 11 bit mode.  The analyzer compensates for the missing three bits by displaying possible combinations for the captured data.  For instance, while sending the letter ‘A’, binary 01000001, to the HD44780, the analyzer only sees 01000.  It performs all the combinations for the three missing bits and when displaying the message for this data it shows Write(@,A,B,C,D,E,F,G).  This mode is selected by indicating the first three channels of data are ‘None’ in the configuration screen.  This mode is supported in both the Logic and Logic 16 devices.

Figure 2 – 8 bit mode

The 7 bit mode, uses 3 channels for control and 4 channels for data.  This mode is supported in both the Logic and Logic 16 devices and correspond the 4 bit data mode of the HD44780.  This mode is selected by indicating the first four channels of data are ‘None’ in the configuration screen.

Figure 3 – 7 bit mode

The position within the enable pulse where the signal for all channels is measured can be controlled between 0 and 99%.  This has come handy while analyzing code that checks for the busy flag in a tight loop as opposed to providing multiple requests to read the busy flag. The analyzer can generate three types of test patterns.  An initialization sequence, the text “The Quick Brown Fox Jumps Over The Lazy Dog” or you can type your own text in the provided text box.  These data generation options are helpful while testing the analyzer without the Logic or Logic 16 connected to the computer.  Let’s install the analyzer and perform a quick test.

Installation

The binary file and source code are located at Codeplex in the HD44780 Protocol Analyzer project.  Download the binary file from the download area, unzip it  and copy to HD44780Analyzer.dll to the Analyzer directory of the Logic 1.1.15 installation.  In my Windows 7 PC this directory is located at “C:\Program Files\Saleae LLC\Analyzers”.  Note this release of the analyzer is only for windows.  Porting it to Linux and Mac should not be a complicated task.  Once you have copied the file, launch the Logic 1.1.15 software and under the Analyzer menu on the right hand side of the screen you should see HD44780-V1.0.0.1.  The V1.0.0.1 corresponds to the version of the dll.

Configuration

To get started testing the HD44780 Protocol Analyzer, make sure your Logic/Logic 16 is not connected to your computer.  This will allow you to select a demo Logic/Logic 16 device and run the simulations contained in the code.  From the options menu select Connected Devices/Demo Logic 16.

Figure 5 – Device Selection

On the first channel, select the option to reset everything, this will clear up any custom names you may have on your channels and make all 16 channels visible.  Hide all channels below channel 10, only channels 0-10 are needed.

Figure 6 – Channel Reset

Edit the settings of the analyzer and make sure all data channels look like that of picture 1 and the Data Generation option is set for 8|4 Bit Initialization Sequence.  Save the settings and select the option to rename the channels, this makes the analysis easier.  Select 2 M Samples at 16Mhz and click the Start Simulation button at the top of the screen.  Note the Start Simulation option is only available when the device is not connected.

Figure 7 – Simulation

Zoom in on the first command sent to the HD44780 and you should see the information depicted in figure 8.

Figure 8 – Simulation Results

The name of the function and its parameters are displayed in a bubble on the enable (E) channel.  SetInterface commands sent as part of the first 5 commands are considered initialization commands and marked with the icon with the number 1 in a circle.  The location of the icon indicates the position in the pulse where all the channels are measured.  Table x illustrates the text displayed by the analyzer for the different commands supported by the HD44780.

Command7/11 Bit Mode8 Bit Mode
No operationNoop()[Noop,Clear,ReturnHome,EntryMode]
Write Data to DDRAMWrite(character)Write( c1,c2,c3,c4,c5,c6,c7,c8)
Read Data from DDRAMRead(character)Read( c1,c2,c3,c4,c5,c6,c7,c8)
Check Busy FlagBusy(on) | Busy(off)Busy(on) | Busy(off)
Clear DisplayClear()[Noop,Clear,ReturnHome,EntryMode]
Return HomeReturnHome()[Noop,Clear,ReturnHome,EntryMode]
Entry ModeSetMode( cursor{dec|inc}, shift{on|off} )[Noop,Clear,ReturnHome,SetMode]
Display ControlSetDisplay( display{on|off}, cursor{on|off}, blink{on|off} ) SetDisplay( ?,?,? )
Cursor or Display ShiftSetCursorAndDisplay(cursormove|displayshift, shift{right|left})SetCursorAndDisplay(cursormove|displayshift, ?)
Function SetSetInterface({4|8}bits,{1|2}lines,5x{8|10})SetInterface({4|8}bits,{1|2}lines,?)
Set CGRAM AddressSetCGRAM(address)SetCGRAM(a1,a2,a3,a4,a5,a6,a7,a8)
Set DDRAM AddressSetDDRAM(address)SetDDRAM(a1,a2,a3,a4,a5,a6,a7,a8)

In 7 bit mode, the start frame and end frame are properly identified with a green circle and a square red dot.  The text bubble is displayed over both frames.  Changing the measure position in the setting interface moves the frame marking accordingly.  There is also minimalistic error tracking in 7 bit mode to detect if the control lines are different between the transmission of the first and second nibble of data to the HD44780.

Data Export

This version of the analyzer allows exporting the captured data to two different types of reports.  The first report generates a CSV file so you can manipulate the raw data for each captured frame in a spreadsheet.

Figure 10 – Data Export

The second report generates the commands for a sequence diagram that you can plugin at websequencediagrams and generate a graphical representation of the commands.  Figure 11 illustrates a portion of the sequence diagram generated for the message Hello World! in 11 bit mode.

Figure 11 – Sequence Diagram

Testing

I have tested analyzing the HD44780 protocol in 7 and 8 bit modes using the HD44780 Library by SA Development from AVRFreaks forum.  If you are the lucky owner of a Logic 16 and can test an implementation of an LCD driver and provide feedback on the result, it would be greatly appreciated.  I am planning on testing the Arduino LiquidCrystal library as well to validate the code behaves as expected.

Future Release

That’s all for this release.  In a future release I am considering adding an HTML report with some options to replay the captured stream.  There are also opportunities for enhancing the detection of the initialization sequence and reporting when the commands or signal timing is outside of the specs provided by the datasheet.

Reversing Bits In A Byte

I am working on a small project that requires interfacing a HD44780 20×4 LCD display to an ATTINY 2313 chip. While designing the PCB for this project, I needed to route the lower nibble of PORTB (PB0-PB3) to the high nibble of the LCD data (D4-D7). Keeping the port mapping straight (PB0->;D4, PB1->;D5, etc) required the addition of at least 6 vias. Reversing the order of the bits ( PB0->;d7, PB1->;D6,etc) required no additional vias, but the content of the lower nibble in PORTB would have to be reverse in code in order to align the data properly. This post documents the analysis I did on different bit reversing routines to determine which one was the most efficient for the task.

I found two viable C implementations to reverse the bits in a byte. Listing 1, illustrates the C code for the reverseByteWithForLoop implementation and the assembly code generated by the compiler. This functions loops through every bit in a byte and reverses every bit that is set. The function is 28 bytes long and takes 92 cycles to run when the data is 0×00 and 100 cycles when the data is 0xFF. It represents 1.37% of the 2K of flash memory in the ATTINY2313.

uint8_t reverseByteWithForLoop( uint8_t num )
{
uint8_t bit;
uint8_t output;
for( int count=1;count>;1;
output = output<;if(bit==1)
output = output+1;
}
return output;
}
/* ===============ASSEMBLY CODE ==================
 ldi	r18, 0x08			; 1 cycle
 ldi	r19, 0x00			; 1 cycle

 mov	r20, r24			; 1 cycle
 andi	r20, 0x01			; 1 cycle
 lsr	r24					; 1 cycle
 add	r25, r25			; 1 cycle
 cpi	r20, 0x01			; 1 cycle
 brne	.+2      			; 1 or 2 cycles
 subi	r25, 0xFF			; 1 cycle
 subi	r18, 0x01			; 1 cycle
 sbci	r19, 0x00			; 1 cycle
 brne	.-20     			; 2 cycles

 mov	r24, r25			; 1 cycle
 ret					; 4 cycle
*/

Listing 2, contains the source code and the assembly code generated by the compiler for the function reverseByteWithShifts. This function is 32 bytes long and takes 19 cycles to run independently of the data. The size of the function represents 1.56% of the available flash memory in the ATTINY2313.

uint8_t reverseByteWithShifts( uint8_t x )
{
x = ((x >;>; 1) &amp; 0x55) | ((x <;<; 1) &amp; 0xaa);
x = ((x >;>; 2) &amp; 0x33) | ((x <;<; 2) &amp; 0xcc);
x = ((x >;>; 4) &amp; 0x0f) | ((x <;<; 4) &amp; 0xf0);
return x;
}
/* ===============ASSEMBLY CODE ==================
 mov    r25, r24            ; 1 cycle
add    r25, r25            ; 1 cycle
andi   r25, 0xAA           ; 1 cycle
lsr    r24                 ; 1 cycle
andi   r24, 0x55           ; 1 cycle
or     r25, r24            ; 1 cycle
mov    r24, r25            ; 1 cycle
add    r24, r24            ; 1 cycle
add    r24, r24            ; 1 cycle
andi   r24, 0xCC           ; 1 cycle
lsr    r25                 ; 1 cycle
lsr    r25                 ; 1 cycle
andi   r25, 0x33           ; 1 cycle
or     r24, r25            ; 1 cycle
swap   r24                 ; 1 cycle
ret                        ; 4 cycle
*/

Listing 3, contains the last function which is my own implementation in assembly language. It is 12 bytes long and uses a loop to reverse all the bits in a byte. It takes this function 37 cycles to complete the task. The size of the function represents 0.59% of the available flash memory in the ATTINY2313.

#if (__GNUC__ * 100 + __GNUC_MINOR__) <; 303
#error &quot;This library requires AVR-GCC 3.3 or later, update to newer AVR-GCC compiler !&quot;
#endif

#include <;avr/io.h>;
.global reverseByte
.func   reverseByte
reverseByte:
ldi        r25, 0x80
rotate_bit:
rol        r24
ror        r25
brcc       rotate_bit
mov        r24, r25
ret
.endfunc

Table 1

Table 1, illustrates the characteristics previously outlined for each one of the functions. This analysis begs the question, which one of these functions is better? Well, it depends. If execution time is the primary concern, reverseByteWithShifts is the best choice at the expense of 1.56% of flash memory. On the other hand, if code size is the driving concern, reverseByte is the best candidate, but it takes twice as long as to run. ReverseByteWithForLoop is smaller than reverseByteWithShifts, but takes the longest to run. Its execution time is dependent on the input data, which makes it a bit more complicated to use in an project that requires accurate timing. To see other alternatives and how this topic evolved over time, visit AVRFreaks. As far as my project goes, reverseByte is the way to go since space concern is more important than execution timing.

Setting Up A Mercurial Repository In Ubuntu 11.10

I have been running Mercurial for a couple of years on a hacked DLINK DSM-G600 network storage device. For a small budget and low power solution, the funplug hacks available for the DSM-G600 work very nicely. I have outgrown this configuration and needed more space, backup options and faster data transfers than what is provided by the DSM-G600. To accomplish this, I setup Ubuntu 11.10 (Oneric Ocelot) in an old PC and installed a pair of 2TB Seagate hard drive in RAID1 mode (mirrored) to increase the reliability of the repository. This post documents step by step the configuration of Mercurial in Ubuntu 11.10.

Requirements

Before getting intimate with apt-get, let’s discuss the requirement for the installation of  Mercurial.

  1. A 2TB mirrored drive will be used to host the Mercurial repositories. The path to the drive is /media/disk1.
  2. The Mercurial server needs a static IP address in order to have a consistent location for clients to use.
  3. An entry will be created in the client host file to access the Mercurial server by name rather than IP address. If you have your own DNS server, this step is not required. For my installation the name of the server will be alexandria, as in the library.
  4. All remote access to the Mercurial server will be done using the http protocol. An installation of Apache is required.
  5. All remote access to Mercurial will require a user id and password. Since this is a personal installation, only one user will access Mercurial.

Overview

To put the installation in perspective, its best to agree on what is it we are going to accomplish. Figure 1, illustrates how the different components related to Apache, security and Mercurial interact with each other.

Figure 1

All the configuration files with a red star will be modified during the installation and configuration of Mercurial. Table 1, contains a description of the different configuration files involved in the installation.

FileDescription
mercurial.configApache configuration file with information about the CGI script responsible for handling requests against the Mercurial repository URL.
hgusersPassword file with the encrypted user id and password of the users who are allowed to access Mercurial through the web.
hgweb.cgiCGI script responsible for passing the web request to Mercurial
hgweb.configConfiguration file that points to the location where the repositories are stored.
hgrcMaster Mercurial configuration file with global settings for the product.

A developer using the command line hg tool or TortoiseHg sends request to a well defined repository URL in Apache. Apache knows how to handle the request by virtue of a mercurial config file which reference the hguser password file to handle security and invokes the hgweb.cgi to handle the actual request. The hgweb.cgi file knows which Mercurial routines to invoke and how to get to the repositories via the hgweb.config file. Mercurial reads global settings from the hgrc config file. This is a simplistic view, but should give you a general idea how the entire configuration is put together.

Installation

This tutorial assumes you can understand simple bash commands, have physical or remote access to the Ubuntu server and have configured the space where the Mercurial repository is going to be installed. Let’s get started.

Step 1 – Assign a static IP address to the server

Follow this instructions to assign a static IP address to your server. This will make the interaction between the server and the client consistent every time.

Step 2 – Add entry to client host file

Follow this instructions to add an entry to your host file in Windows 7. This will allow you to browse or use the hg command line tool without having to remember the ip address of the server. After performing this step you can open a command window and ping the server by name. In my case ping alexandria shows the Ubuntu server is online. See Figure 2.

Figure 2 – Pinging Mercurial Server

Step 3 – Update UBUNTU Software and check version

Connect to the Ubuntu server and open a shell to verify the software in your server is up to date. While you are at it, verify the version of Ubuntu you are running. I performed my installation from a Windows 7 PC using Putty to connect over ssh to the Ubuntu server.

sudo apt-get update #Update software packages
lsb_release -a #Verify Ubuntu version

Step 4 – install apache

Install Apache if you already haven’t. You can check if Apache is already installed by pointing a web browser to the Ubuntu server and see if the “It Works!” message is displayed. If not, install Apache with the command below. Alternatively you can test directly from the shell by doing a wget localhost. You will see the 200 OK response code.

sudo apt-get install apache2 #Install Apache server
wget localhost #optional verification Apache is running

Step 5 – install mercurial

Next step is to install Mercurial.

sudo apt-get install mercurial  #Install mercurial

Step 6 – configure master hgrc configuration file

Now that Mercurial is installed, let’s configure the master hgrc configuration file. The goal is to enable the following functionality.

  • Remove Mercurial SSL restrictions
  • Allow to push repository from the web
  • Allow repositories to be downloaded in multiple compressed formats
  • Trust the user www-data. This is the the account used to run Apache. Not having www-data as a trusted user in the hgrc config file generates a nasty error while updating a repository.
sudo nano /etc/mercurial/hgrc
#type the following in the hgrc file
[web]
allow_push = *
push_ssl = false
allow_archive = gz, zip, bz2
[trusted]
users = www-data

Step 7 – Configure personal hgrc FILE in server

Configure your personal .hgrc file in the Ubuntu server with your user name. This file gives you the opportunity to personalize the Mercurial experience.

cd ~  # go to home directory
nano .hgrc
#type the following
[ui]
username = Your Name

Save the file and proceed to the next step.

Step 8 – create sample repository

Let’s create a sample repository right at the root of your home drive. We’ll use this repository later to test access to Mercurial through the web server.

cd ~  # go to home directory
mkdir repository1
cd repository1
hg init
echo Hello World! > readme.txt
hg add readme.txt
hg status
hg commit -m 'My first repository!'
hg tip  # shows the tip of the repository

We have just finished creating a repository with one readme.txt file in it.

Step 9 – Configure mercurial base directory

Next step is to configure the directory from where Mercurial is going to serve repositories via Apache. As stated before, the location for the installation of the the repository is /media/disk1/mercurial, if you are not using a dedicated drive chances are the location of your repositories is /var/hg.

cd /media/disk1/
sudo mkdir mercurial
sudo mkdir mercurial/repositories
#Change the owner of the repository to the Apache user
sudo chown -R root:www-data mercurial

Step 10 – Configure mercurial web configuration file

Let’s configure the hgweb.config. For now we only need two entries in the file. One to control display style and the other to indicate where is the repository. Open a new hgweb.config file with nano or vim, enter the text below and the save the file.

cd /media/disk1/mercurial
sudo nano hgweb.config

Enter the text below and save the file.

[web]
style = gitweb

[collections]
/media/disk1/mercurial/repositories = /media/disk1/mercurial/repositories

Step 11 – Configure mercurial cgi sCRIPT

Let’s configure the hgweb.cgi script in order to serve the repositories via Apache. Instead of writing an entire file ourselves, we’ll use the one provided by Mercurial and make the necessary modifications.

cd /media/disk1/mercurial
sudo cp /usr/share/doc/mercurial/examples/hgweb.cgi . # do not forget the dot at the end
sudo chmod a+x hgweb.cgi

Open hgweb.cgi with nano or vim and find the line that reads config=….. and replace with the following.

config = "/media/disk1/mercurial/hgweb.config"

Step 12 – register mercurial cgi with apache

Next let’s configure Apache so it runs the hgweb.cgi when the /mercurial virtual directory is requested. Instead of modifying the default configuration file, let’s create a separate configuration file and link it to the default Apache configuration file.

cd /etc/apache2
sudo mkdir mercurial
cd mercurial
sudo nano mercurial.conf

Type the following in the mercurial.conf file. Note I have intentionally left security out of the file in order to test the installation without security first.

ScriptAliasMatch ^/mercurial(.*) /media/disk1/mercurial/hgweb.cgi$1
<Directory "/media/disk1/mercurial/">
Options Indexes FollowSymlinks MultiViews ExecCGI
AllowOverride All
Order allow,deny
Allow from all
AuthType Basic
AuthName "Mercurial Repositories"
AuthUserFile /media/disk1/mercurial/hgusers
Require valid-user
</Directory>

The next set of commands link the mercurial.conf file to Apache. This let the web server knows how to handle requests to /mercurial.

cd /etc/apache2/sites-available
sudo nano default
# Type on the line before
Include /etc/apache2/mercurial/mercurial.conf

#restart the apache server so the changes take effect
sudo apache2ctl restart

Step 13 – Test web access to repository

Let’s copy the test repository we created to /media/disk1/mercurial/repositories in order to serve it through the web. Note you need to change the owner of the directory structure in order for Apache to serve the directory properly.

cd ~ # go to your home drive
sudo mv repository1 /media/disk1/mercurial/repositories/.
sudo chown -R root:www-data /media/disk1/mercurial

Launch your browser pointing to http://servername/mercurial. You should see one repository with the options to download in multiple compressed formats. See Figure 3 for reference.

Figure 3 – Browsing Repository

Before running the next steps to test cloning the repository, let’s do a a bit of cosmetic housekeeping on repository1. Let’s populate the description and contact.

cd /media/disk1/mercurial/repositories/repository1
cd .hg
sudo nano hgrc
#type the following
[web]
contact = Omar Francisco
description = Hello World Project!

Refresh your browser and how you should see the contact and the description populated. Nice!

Figure 4 – Merurial Repository With Cosmetic Changes

Step 14 – Clone Repository From Client PC

Let’s test cloning and then updating the repository. From the windows client computer open and command window and perform the following steps.

cd %USERPROFILE%/documents     # go to the documents folders
hg clone http://alexandria/mercurial/repository1    #clone repository1
cd repository1   # go to the repository
dir c:\ > readme.txt  # update readme file
hg status # see the file readme.txt has been modified
hg commit -m "Remote Changes To Readme File"
hg push http://alexandria/mercurial/repository1

Browse to the repository and click on the repository1 link. You should see information similar to that of figure 5.

Figure 5 – Remote Update

We have reached a milestone in the installation of Mercurial. If you are not interested in security, then this is it. We are done. If on the other hand you want to secure access to your repositories, then continue reading.

Step 15 – Configuring security

In order to configure security, we need to instruct Apache to only allow access to users who are registered in a password file.

cd /media/disk1/mercurial
# create password file - need to type user password twice
sudo htpasswd -mc hgusers hgadmin
sudo chown root:www-dta hgusers
# type the password twice - repeat command for more users

Edit the mercurial.conf file in /etc/apache2/mercurial to read as follows

ScriptAliasMatch ^/mercurial(.*) /media/disk1/mercurial/hgweb.cgi$1
<Directory "/media/disk1/mercurial/">
Options Indexes FollowSymlinks MultiViews ExecCGI
AllowOverride All
Order allow,deny
Allow from all
AuthType Basic
AuthName "Mercurial Repositories"
AuthUserFile /media/disk1/mercurial/hgusers
Require valid-user
</Directory>

This changes configure Apache to allow users registered in the /media/disk1/mercurial/hgusers file to browse the repository. Be extremely careful typing the modifications to the mercurial.config file. Apache is very unforgiving of typographical mistakes. In the event you get errors while trying to login through the web check the /var/log/apache/error.log for the cause. For your reference,  figure 6 contains a listing of the /mercurial directory after the installation is completed.

Figure 6 – Mercurial Directory Listing

Performing a hg clone http://alexandria/mercurial/repository1 now requires the user to provide an ID and password in order to have access to the repository.  We are done, go and write some code to test drive your Mercurial installation.

PCB Inspection Using The Veho Discovery Digital Microscope

Creating your own PCB seems to be an unavoidable task for every electronic enthusiast.  Even when you plan to use a professional service to create the final PCB for your project, developing the skills to create your own PCB for prototypes and small projects will save you money and give you quick gratification.  To assist with the PCB creation process I wanted a relative inexpensive digital microscope to inspect PCBs and solder joints.  I had a $100 dollar budget.  Over a  couple of nights I researched available microscopes within my budget.  I must say I was most impressed with the Dino-Lite family of products, unfortunately the cost of these units was outside of my budget.  At the end of my research I settled for the Veho VMS-0004 Discovery.  This post documents my first impressions of the Veho VMS-0004 microscope in the context of PCB design.

Installation

I picked a Veho Discovery from J&R in New York City for $69.99 + taxes.  The unit comes in a slick cylindrical package.  It comes with drivers for the MAC and PC.  Unfortunately the CD is a small format and did not fit in my iMac.  I had to use my laptop to transfer the content of the CD to a USB thumb drive in order to proceed with the installation.   I installed the software in the Windows 7 64 bit partition of my iMac without any problems.   Figure 1 contains a picture of the Veho and its base.

Veho Microscope

Figure 1 – Veho Microscope

Test Run

The Veho software let’s you take pictures and videos at high resolution.  It also lets you measure objects as long as you provide the magnification from the microscope.  I had mixed results with this feature.  Figure 2 contains a picture of the MEGA82U micro controller and crystal in an Arduino Uno board at a 32x magnification.  I have boxed in green the different measurements I took on the Arduino Uno.  You will need to play with the magnification factor in order to get decent measurements.

Veho - Arduino Uno Snapshot

Picture 2 – Veho – Arduino Uno Snapshot

Figure 3 contains a picture of a broken trace in a PCB.  The magnification of this picture is 30x.  The broken trace is very difficult to see with the naked eye.

Veho - Broken PCB Trace

Figure 3 – Veho – Broken PCB Trace

Figure 4 shows a hall effect sensor and a SMD resistor.  The area in red shows a solder joint that needs additional work.  The magnification for this picture is 30X.

Veho - Hall Effect Sensor

Figure 4 – Veho – Hall Effect Sensor

Figure 5 shows a portion of a trace magnified at 400x.  You can see imperfections impossible to see with the naked eye.

Veho - Trace 400X

Figure 5 – Veho – Trace 400X

The following video contains a few shot of a different PCBs.  Hopefully you can see the level of magnification you can achieve with the Veho.

Conclusion

The Veho is made of hard plastic. The base is very light and tips over if the microscope is pushed too much forward.  I am considering making a more robust base using PVC.  The image quality is very good and the unit does a good job providing light to the area under inspection.    For $69.99 + taxes, the Veho Discovery is a nice addition to your electronic workbench.

I2C Bus Scanner

Attaching components to an I2C bus can be a tedious experience when things do not go right.  Many factors ranging from bus termination, cross over cables and faulty devices can drive you to drink while debugging a problem.  I have been using a PDE created by Tod E. Kurt to perform bus scanning when troubleshooting connectivity to I2C components.  This post discusses modification made to the code provide by Tod and its conversion to an Arduino library.  The I2CScanner class is meant to be used as a debugging tool.  It assumes the bus is operational.  This class has little value if you are trying to bit bang an implementation of the I2C protocol.  The class satisfies two primary use cases.  Scanning the I2C bus and displaying the status of each address and determining if a device is listening to a particular address.

Installation

The following steps describe how to download and install the library.

  1. Download the file i2cscanner.zip and unzip to a temporary directory.  It contains the files i2cscanner.h, i2cscanner.cpp and i2cBusScannerDemo.pde.
  2. Create a directory named i2cscanner in the library directory of your Arduino installation.
  3. Copy the files i2cscanner.h and i2cscanner.cpp to the newly created i2cscanner directory.
  4. Load the pde and run

Using The Library

Listing 1 contains the code of a demo PDE that tests the different methods of the class.  The method I2CScanBus::isAddressOnBus(byte address) has been very helpful while creating unit tests to test code that interface with I2C components.  The other method of the class, scanBus(..) and its overloads, allow finer control of the range of addresses to include and how to display the report generated when the I2C bus is scanned.

#include <Wire.h>
#include <i2cscanner.h>
using Utilities::I2CScanBus;
void setup()
{
/* Initialize libraries */
Wire.begin();
Serial.begin(19200);

/* Scan I2C bus from address 1 - 127 */
I2CScanBus::scanBus();

/* Check if there is a device at address 103 */
Serial.print("\nSearching for address 103...");
if ( I2CScanBus::isAddressOnBus(103) )
Serial.println("Device Found");
else
Serial.println("Device NOT Found");

/* Scan I2C bus from address 10-20 */
I2CScanBus::scanBus(10,20);

/* Scan I2C bus from address 1 - 127, display addresses in HEX using two columns */
I2CScanBus::scanBus(1,127, I2CScanBus::NUM_HEX, I2CScanBus::TWO_COLUMN);
}

void loop()
{

}

Figure 1, shows the partial output of the report generated by running the code in the sample pde.  Addresses are displayed in decimal and hex.  Option to display the address in binary or octal is available as well.

Scan Bus Report

Figure 1 – Scan Bus Report

Once you have the sample sketch setup you can run it any time you need to scan the bus.  Alternatively you can reference the library and scan the bus from within your  project as needed.

 I2CScanner Source Code

WordPress TwentyEleven Theme – Show Only Sticky Posts In Home Page

Introduction

As part of the customization of my site, I want to display only sticky posts on the home page.  On the average I expect to have one sticky post at the time.  This post documents how to modify the TwentyEleven Theme in WordPress 3.2 to achieve this functionality.

Implementation

Visit ThemeFm for a good overview of the TwentyEleven theme. This is really a one liner.  Open the index.php template, and insert the <?php if(!is_sticky() && (is_home() || is_front_page()) ) break;  ?> line just before the get_template_part(…) call.

<?php /* Start the Loop */ ?>
<?php while ( have_posts() ) : the_post(); ?>
<?php if(!is_sticky() &amp;amp;amp;amp;amp;amp;&amp;amp;amp;amp;amp;amp; (is_home() || is_front_page()) ) break;  ?>
<?php get_template_part( 'content', get_post_format() ); ?>

This line of code check if the post is not sticky and the home or front page is being display.  If this condition is met it aborts the loop.  This works because WordPress displays all sticky posts first.  That’s it we are done.

WordPress TwentyEleven Theme – Taming Category And Archive

Introduction

I am a new to WordPress.  My site is running WordPress 3.2 with the TwentyEleven theme.  I wanted to change the way posts under archives and categories are displayed.  Instead of listing all the posts, I want to list the title of the post and a summary.  This post describes the simple changes that need to be done to the TwentyEleven theme to accomplish this change in functionality.

Implementation

Visit ThemeFm for a good overview of the TwentyEleven theme.  The content.php page, which is the page with the default template to display all post, has logic to display the summary of the post when it is displayed in a search.  That’s exactly what I want to do when displaying the list of posts in a category or in an archive.  Step 1, is to make a copy of the content.php template and to name it content-archive.php.
Step 2, requires minor modifications to the content-archive.php page.  Look for the following code in the content-archive.php.

?php if ( is_search() ) : // Only display Excerpts for Search ?>
<div>
<?php the_excerpt(); ?>
</div><!-- .entry-summary -->
<?php else : ?>
<div>
<?php the_content( __( 'Continue reading <span>&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;rarr;</span>', 'twentyeleven' ) ); ?>
<?php wp_link_pages( array( 'before' => '<div><span>' . __( 'Pages:', 'twentyeleven' ) . '</span>', 'after' => '</div>' ) ); ?>
</div><!-- .entry-content -->
<?php endif; ?>

Replace this block of code for the following code in order to force the the template to behave as in search mode.

<?php // display Excerpts for archive ?>
<div>
<?php the_excerpt(); ?>
</div><!-- .entry-summary -->

At this point we have a template that displays the title of the post with date information and the summary.  Step 3, requires linking the content-archive template to the archive and category display.  Open the Category Template (category.php) and replace the following code

get_template_part( 'content', get_post_format() );

with the following line in order to link the content-archive to the category display.

get_template_part( 'content', 'archive' );

Repeat the same step for the Archive Template (archive.php) and that’s it, you are done.  Settings->Reading allows you to control how many posts to list per page.

The I2C Bus Terminator – Hasta La Vista Baby!

Introduction

After breaking the leg of another resistor while setting up a I2C bus.  It was time to permanently fix this problem.  The Atmega328 has one single I2C bus.  I am testing with software to bit bang data on any two pins of the AtMega328.  See SoftI2CMaster for more information.   I am also testing with the PCA9546A to provide access to multiple I2C buses.  Yes, pinky we are taking over the world tonight! The problem is all the I2C buses need to be properly terminated and bending the legs of the same set of resistors will eventually break them.  As my father used to say, they do not make ‘em like they use to.

Requirements

I need a solution that allows me to wire an I2C bus quickly and without bending pins.  The solution must be breadboard friendly and not complicated to use.  It should have connection pins so jumper wires are not required.  It took no time to create a simple three pin, two resistor solution that plugs in nicely into my Cohiba Breadboard main data bus.  It can also be used to terminate additional I2C buses.

Implementation

I plan to create about 6 units to keep them around to breadboard prototypes.  The pullup resistors are 4.7K.  This schematic cannot be any simpler.  The following pictures list the schematic, PCB layout, 3D design and the first model.

I2C Bus Termination

I2C Bus Termination

I2C Bus Termination PCB

I2C Bus Termination PCB

I2C Bus Termination 3D

I2C Bus Termination 3D

I2C Side View

I2C Side View

I2C Breadboard View

I2C Breadboard View

Conclusion

I welcome with opened arms any solution or tool that allows me to maximize the time I spend working on projects as opposed to building infrastructure to prototype or test it.  Having a couple of these I2C bus terminators around, is a small but nice addition to the toolbox.

Enhancing How Applications Capture Customer Address

Introduction

An accurate customer database is one of the most valuable assets a business can have. Incorrect customer addresses increase the cost of doing business and reduces profit margins. On May 17 of 2009, The United States Post Office published in the National Postal Forum Summit the annual cost of Undeliverable As Addressed (UAA) mail is estimated to be $1.856 billion. 12.4% of this amount is related to addresses with bad elements. Figure 1 contains a breakdown of the different reasons why mail is not delivered. The cost of fixing a customer address varies depending on the complexity and cost of a business process or the stage of the process at which the address discrepancy is found. This article analyses a couple of cost effective and easy to implement solutions to reduce the number of records with incorrect address due to bad address elements.

usps chart

Figure 1, Mail Delivery Failure

Quantify the Problem

For a company like Amazon, a shipment with a bad address represents additional cost and an exception in the business process. For a smaller company like the guys mowing my lawn, a bad address represents a delay in revenue since customers cannot be billed on time. Independently of the business line or application for which you want to introduce the techniques outlined in this article, it is important to understand the scope of the problem and quantify the cost to the business. This information will allow you to measure the effectiveness of the solution at different time periods after implementation. Financial matters aside, let’s discuss specifics.

Typical Address Capture

Figure 2 illustrates a HTML form capturing a customer address. Similar forms can be found in e-commerce web sites or in-house applications. The layout of the form is human friendly and does not give the application an opportunity to proactively fill in address information based on related data elements. The user is required to enter the entire address and at that point the address is ready for validation.

Classic Form

Figure 2 – Classic Address Form

Enhanced Address Capture – Round 1

Figure 3 rearranges the form to allow the application to obtain related data elements as the operator enters information. This approach enhances the user experience and increases the accuracy of the address information. An additional visual element has been introduced to display the address in USPS format. This implementation uses the following data elements relationships.

  • A successful reverse telephone lookup can generate the customer address.
  • A zip code lookup can generate the city and state of the address. This will require the customer/operator to enter only the street address.
Enhanced Form

Figure 3 – Enhanced Form

Enhanced Address Capture – Round 2

Figure 4 provides an implementation aimed to Customer Service Representatives (CSR). It provides a similar address resolution scheme to the previous solution. It also adds value by including an embedded Google map and enhanced spelling for targeted fields using NATO phonetic alphabet. This last feature is activated by placing the mouse over the field label and is a result of observing CSR work with different customers while creating new accounts or making modifications to existing ones. A CSR usually spells back to the customer email, city, address and name. In my experience, the number of fields that get spelled back to the customer depends on factors such as familiarity of the customer or CSR with the English language, speaker accent, quality of phone connection or complexity of the data. For instance, 30 Maine Street can be easily understood as 30 Main Street due to any of the conditions previously listed.

Another advantage of introducing a common spelling solution is the NATO phonetic alphabet can be replaced or modified to include words that mask the CSR accent. This facilitates the communication between customer and CSR and provides consistency to the task of spelling information back to the customer. 30 Main Street will be unambiguously spelled by all CSRs as three, zero, Mike, Alfa, India, November, Space, Sierra, Tango, Romeo, Echo, Echo, Tango.

Full Form

Figure 5 – Full Form

Using the Code

The code is broken in three main tiers. The presentation tier running on the browser and composed of address.html, tutorial.cs, tutorial.js and additional JQuery plugins for general UI support. The middle tier on the web server where the proxy for the reverse telephone lookup runs in the form of an Ajax WCF web service and the data layer where the data provider (whitepages, Google, etc.) stores telephone registration information. The HTML form is setup to run as a singleton in the tutorial.js file.

var theForm = new function MainForm() {
    var instance = null;
    var controller;
    this.getInstance = function() {
        if (instance == null) {
            instance = this;
            init();
        }
       return instance;
    }
    function init() {
        controller = new FormController
		(new InputAddressView(), new FriendlyAddressView());
        controller.init();
    }
}

$(document).ready(function() {
    theForm.getInstance();
});

The initialization of the form takes place during the document ready event generated by JQuery. Two composite views are created, one responsible for capturing user input and managing the map control, the other responsible for displaying the address in USPS format. The controller is responsible for sending/receiving data to/from the middle tier and handling events generated by the InputAddressView control. During initialization, the FriendlyAddressView registers with the controller to receive notification when address information changes. The InputAddressView does not need to register for notification since it is the only view capable of modifying the customer address. The controller initializes the views with default data, configures the reverse phone lookup proxy and notifies all subscribed views the main view has changed. All this displays a form with all fields blank ready for user input.

this.init = function() {
	_inputAddressView.init(THIS);
	_friendlyView.init(THIS);

	addressData = Data.Repository.getNewCustomer()
	setAddressView();
	proxy.setHandler(onTelephoneLookupHandler);
	fire(this);
}

The initialization of the InputAddress dynamically creates each input control (telephone, cellphone, zipcode, etc.) by providing the HTML placeholders where the labels and fields need to be generated. Each control is responsible for generating the input field it represents with the necessary label, masking, length, events, etc.

var _controller;
var zipCode = new CustomTextBox("zipCodeContainer",
	"zipCode3", "", "", "Zip", "", "99999", 5, onZipCodeKeyUp);
var state = new stateComboBox("stateContainer", "state3",
	"StateClass", "", "State", "ZipClass", onStateChange);
var cmbState1 = new stateComboBox("stateContainer1", "state1",
	"StateClass ReadOnly", "DC", "State", "ZipClass");
var cmbState2 = new stateComboBox("stateContainer2", "state2",
	"StateClass ReadOnly", "DC", "State", "ZipClass");
var street = new PhoneticTextBox("streetContainer", "streetAddress3",
	"TextBox", "", "Street Address", "", onStreetKeyUp);
var city = new PhoneticTextBox("cityContainer", "city3",
	"TextBox", "", "City", "", onCityKeyUp);
var fullName = new PhoneticTextBox("fullnameContainer",
	"fullName3", "TextBox", "", "Full Name", "", onFullNameKeyUp);
var email = new PhoneticTextBox("emailContainer", "email3",
	"TextBox", "", "Email", "", onEmailKeyUp);
var cellphone = new telephoneTextBox("cellphoneContainer",
	"cellphone3", "", "", "Cell", "", onCellphoneKeyUp);
var telephone = new telephoneTextBox("telephoneContainer",
	"telephone3", "", "", "Telephone", "", onTelephoneKeyUp);

The telephoneTextBox control is configured to notify the form when the phone field is complete. The form notifies the controller which in turn captures the new telephone number, notifies any view subscribed for notification and requests the reverse phone lookup proxy to perform a lookup.

this.onTelephoneChange = function(sender, data) {
	addressData.setTelephone(data);
	fire(sender);
	proxy.telephoneLookup(data);
}

A successful phone lookup is handled by the onTelephoneLookupHandler method of the controller which captures the new data, updates all views and schedules the map refresh to take place the next time a field loses focus. The map cannot be updated while the user is typing because the iframe where the map is located captures the focus during the map update. Not scheduling the map refresh has the side effect of the current field losing the focus and the data if the field has a mask. The reverse phone lookup takes place while the user is entering the cell phone or email for the customer. Note that the use case dealing with multiple persons registered to a single telephone number is not addressed in this example. The first person registered is used for the example provided.

function onTelephoneLookupHandler(data) {
	if (!data.d.found)
		return;
	addressData.setZipCode(data.d.zipCode);
	addressData.setState(data.d.state);
	addressData.setCity(data.d.city);
	addressData.setStreet(data.d.street);
	addressData.setFullName(data.d.name);
	_inputAddressView.setAddress(addressData, true);
	refreshMapOnChange = true;
	fire(this);
}

Figure 5 illustrates a sequence diagram of the reverse phone lookup. As a side note, the diagram was generated with the on-line sequence diagram generator provided by Web Sequence Diagram.

Sequence Diagram

Figure 5 – Sequence Diagram

The zip code resolution uses a similar approach, except instead of calling a web service hosted in the middle tier, one is called hosted at www.geonames.org. The call is triggered by the controller when the zip code has five digits. A successful lookup captures the city and state associated with the zip code and updates the views accordingly.

this.onZipCodeChange = function(sender, data) {
        var zipText = data.replace("_", "");
        addressData.setZipCode(data);
        if (zipText.length == 5)
            $.getJSON("http://www.geonames.org/postalCodeLookupJSON?&country=
		US&callback=?",
            	{ postalcode: zipText }, onLookupResponse);
        else {
            fire(sender);
        }
    }

function onLookupResponse(response) {
	if (response && response.postalcodes.length &&
		response.postalcodes[0].placeName) {
		addressData.setCity(response.postalcodes[0].placeName);
		addressData.setState(response.postalcodes[0].adminCode1);
		fire(this);
		setAddressView();
		_inputAddressView.focusOnStreet();
	}
}

The reverse telephone lookup is handled by the getAddress method of the web service. Multiple components implementing the IAddressRepository interface are provided to experiment performing reverse phone lookups against WhitePages, Google and AnyWho. Each connector submits the data to the site and parses the returned HTML file to get the address information. Note, the usage of public websites to screen scrape telephone information is not recommended for critical applications and may violate the terms of use of the targeted site. Consider the usage of this technique in the context of the provided code as a pedagogical instrument.

[OperationContract]
public Address getAddress(string telephone)
{
	PhoneRepository.IAddressRepository repository =
				new WhitePagesAddressRepository();
	IList<PhoneRepository.Address> list = new List<PhoneRepository.Address>();

	try
	{
		list = repository.getAddress(telephone);
	}
	catch( System.Exception ex )
	{
	}
	Address newAddress = new Address();
	if (list.Count > 0)
	{
		newAddress.city = list[0].city;
		newAddress.state = list[0].state;
		newAddress.zipCode = list[0].zipCode;
		newAddress.street = list[0].address;
		newAddress.name = list[0].firstName + " " + list[0].lastName;
		newAddress.telephone = list[0].phoneNumber;
		newAddress.found = true;
	}
	else
		newAddress.found = false;

	return newAddress;
}

Testing The Code

The project is configured to run inside the web server embedded in Visual Studio and launch the address.html page. Once the page comes up, perform the following tests.

  1. Enter a telephone number – some have been provided as example. While entering the cell information, the address associated with the phone number will be populated. The map is not refreshed until the focus is moved from the current field.
  2. Put the mouse on the label of fields with the spelling icon. The NATO phonetic spelling will be displayed if the field contains text.
  3. Press the spelling icon. This will display a dialog with the NATO phonetic spelling in both English and Spanish and allow modification of the field.
  4. Enter a valid zip code; both the state and city will be updated with the right values.

Conclusion

Reverse phone look up combined with resolution of city and state from a zip code can increase the accuracy of a customer address and reduce the time it takes a CSR to capture this information. Phonetic spelling can standardize the way information is spelled back to the customer and alleviate language related problems. These techniques combined reduce the number of bad addresses in your application database and the time CSRs spend with customers.

Download Source – 369.99 KB

I Want My Cohiba

Introduction

I am organizing my workspace at home in order to streamline how I work on electronic projects.  As a result of this, I needed a second breadboard and multimeter next to my main computer on the first floor. All the heavy equipment (power supply, bench multimeter, solder iron, etc) would be moved to the basement.  While enjoying one of my last two Cohibas, I started jotting down the requirements for this project.

Requirements

I tend to work on one project at the time.  I normally use the ETS-7000 Analog and Digital Trainer as my primary breadboard.  It’s been modified to hold two development boards with the Arduino form factor.  A Fez Panda and an Arduino Uno are part of my arsenal.  See Figure 1, Arduino Uno is missing from the picture.

ETS-7000 Analogue and Digital Trainer

Figure 1 - ETS-7000 Analogue and Digital Trainer

The ETS-7000 does the job, but there have been times when I want to breadboard a concept and the breadboard does not have enough real state or the Arduino Uno is connected to a bunch of wires.  This would be a good opportunity to ease some of these pains and create a platform on top of which I can build up in the future.  The new breadboard system should have the following features.

  1. Large real state to be able to work on complex projects or have multiple  prototypes on the board.
  2. Keep Arduino board fixed to prevent sliding or causing a short circuit.
  3. Portable in order to move between first floor and basement.
  4. Replaceable breadboards in order to swap projects.
  5. Multiple Arduino boards to work on communication projects between Arduinos.
  6. Large unconventional breadboard area in order to test breakout boards.

In a nutshell this covers everything that I need.  Instead of relying on supporting devices (power supplies, LED, switches, etc) permanently attached to the breadboard as in the case of the digital trainer, I would rely on external devices and breakout boards as much as possible.

Implementation

I found the best deal for individual breadboards at Electronic Express.  To host the boards, an empty box of Cohibas with a drawer handle did the job perfectly.  The drawer handle levels both side of the box when it is open. I put the faceplate of an old clock in the front for decoration.   See Figure 2 for an outside view of the box.

Cohiba Board

Figure 2 - Cohiba Board

There is room for two Arduino boards and if the breadboards are empty, you can close the box with the Arduino boards inside.  See Figure 3, for an internal view of the right hand side of the board.

Cohiba Board 2

Figure 3 - Right Hand Side Of Board

The breadboards are attached to a 1/2  inch, 7 x 9 board, that fits nicely in the box of Cohibas.  Attaching the breadboard to the wooden board allows them to be swapped in and out of the box as needed.  The left hand side of the board is fixed and it is screwed to the drawer handle with a flat nut.  The Arduinos are attached independently and can be swapped if necessary.  Figure 4, shows the Cohiba box open with all the breadboard real state.

Full Cohiba Board

Figure 4 - Full Cohiba Board

The outer bus is used as a data bus for I2C and SPI.  The bottom of the left hand side has two breadboards without buses.  This arrangement allows me to use larger than normal breakout boards.  Staples are used to connect the buses as needed.

Conclusion

Independently of the project or field, the ability to make the most of the resources you have is one of the best tools in your arsenal.  You can get empty cigar boxes from your local cigar store.  You may get them for free or for a couple of dollars.  Between cutting and sanding the boards, using a Dremel to trim the connection points of the outer data bus,  it took me a couple of hours to put this project together.  Now all I need is another box with fresh Cohibas to get started on the next project!