Sunday, January 3, 2016

Arduino O&M: Pins and Headers

This article verbally describes the most current Arduino headers and pin locations (version R3) so you can start building things as quickly as possible. It offers a basic orientation to the Arduino board plus specific descriptions of pin locations on the standard headers used for input, output, and control. It also includes descriptions of some non-visual techniques for finding header sockets -- some manual dexterity and sensitivity required.

This article does not orient you to older board configurations or to other components on the board, nor does it go into any detail about specific properties of the pins themselves. That information is readily available elsewhere, but a good start is this article with more information about Arduino pins and their properties.

Basic Orientation

Most Arduino boards are the same shape and size for standardization and interchangeability: a small rectangle about 2.25X2.75 Inches with USB and power ports on one of the short edges, and two rows of header sockets along the two long edges. The headers are narrow, tall blocks, each with a single row of small holes (sockets) along the center of the top face. Each Arduino pin is associated with one of these sockets.

Holding the board with the end that includes the USB and power ports at the top, the headers run vertically along the left and right edges. Both left and right headers are divided into lower and upper sections separated by a small notch. Unfortunately, some headers are manufactured without this notch, making tactile orientation a little harder.Check out this post on dealing with notchless headers for suggestions. In the modern R3 header configuration, the left header has 6 sockets in the lower section and 8 in the upper. The right header has 8 sockets in the lower section and 10 in the upper.

Note: Older boards have header configurations with fewer sockets in the top sections on both left and right.

The lower-left section of 6 sockets is the Analog Section. In order from bottom to top, the sockets are:
A5, A4, A3, A2, A1, and A0.

The top-left section of 8 sockets is mostly related to power supply. From bottom to top, these sockets are:
voltage in, ground pin, another ground pin, 5 volt pin, 3 volt pin, reset pin, I/O reference pin, and an unused pin.

The lower-right header section of 8 sockets is where the digital pins begin. From bottom to top, these are:
D0, D1, D2, D3, D4, D5, D6, and D7.

The top-right header section of 10 sockets continues the digital pins. From bottom to top, the sockets are:
D8, D9, D10, D11, D12, D13, ground pin, analog ref pin, I2C SDA, and I2C SCL.

Non-Visual Techniques for Navigating The Sea of Holes

It’s not easy to feel the sockets in the headers with your fingertips, but there are other ways. Counting the sockets is easy using a probe such as a tooth pick, stiff piece of wire, or an opened paper clip, but you get serious old-school blind cred if you use a stylus!

Often the easiest way is to count your way along a row of sockets with the stripped end of the wire you’re planning to insert. Finally, you can most easily find the gap between upper and lower header sections with a fingernail, or by running the side of the probe along the edge of the header block.


Once again, my thanks to John Schimmel of DIY Ability, this time for transcribing the socket information off of a JPG and for providing awesome background links.

Saturday, January 2, 2016

Arduino Setup and Accessibility Tips for Windows


In a world of talking iPhones, sexy accessibility announcements, and high-quality open-source screen readers, the naive sighted person could be forgiven for assuming that we have finally reached the point where a blind person could simply download and use the same exact software tools as everyone else for any given problem. Blind people know that it is rarely that simple. There are a wide variety of issues that still stand as barriers to equal access in all sorts of situations, and Arduino development on Windows is no exception. While it is definitely possible to set up an accessible development environment for Arduino on Windows, many of the steps may not be immediately obvious, especially to the beginner.

This post is intended to streamline the Arduino setup process, flagging accessibility work-arounds, and providing a step-by-step guide to setting up the tools you’ll need for Arduino development as a blind maker.

More advanced readers may want to check out the detailed source materials. Much of the information in this post comes from a more complete discussion of the Arduino command line on github.

If you are just getting started and don’t know anything about Windows, software development, accessibility, or Arduino, this blog is probably not the best place to start. This article assumes you’re already comfortable with Windows and your screen reader, and that you know what Arduino is and have some motivation to make things with it.

About the Arduino IDE

Arduino sketches and many other kinds of software are usually developed in an application called an Integrated Development Environment (IDE). An IDE allows you to edit your code and turn it into a program that actually runs and does something. In the case of Arduino, the IDE compiles the source code and uploads it to the Arduino board. It also helps you find errors in your code and has many other helpful features.

The Arduino IDE is written in Java which makes it easier to deploy on a bunch of different platforms (i.e., Windows, Mac, and Linux). Unfortunately, Java applications on Windows present some issues for screen readers, and most, like the Arduino IDE graphical user interface, are not readily accessible. It is possible to configure the Java Access Bridge for the Arduino IDE to let NVDA work quite well, but that's the topic of another post.
Luckily, the Arduino IDE also includes a command line interface that lets a blind user access most of its critical features from a Windows DOS Prompt -- that's what this article is all about.

Installing the Arduino IDE

Follow these steps to install the IDE on your Windows machine:

  1. Make sure you have Administrator privileges. If you don’t, you will need to get the owner of the machine to install the software.
  2. Download the Arduino IDE. It needs to be later than version 1.5 in order to support the command line interface.
  3. After downloading, run the Arduino IDE installer and follow the prompts. This should be relatively straight-forward using NVDA or JAWS.
  4. During installation, note the directory in which Arduino is being installed. This will be helpful when configuring the IDE, discussed in the next section.

Configuring the Arduino IDE from the DOS Prompt

The DOS Prompt is a command line interface to your Windows computer. It is a terminal window where you can type commands and the responses to those commands appear as text which scrolls up from the bottom of the window. This post assumes you have used it before and that you have some familiarity with it. If not, do a little reading starting with this nice little
article on the DOS Prompt from the University of Wisconsin Knowledge Base.

The DOS Prompt can be started by opening the Run Dialog (Windows+R) and typing cmd, followed by Return or pressing OK.

When using the DOS Prompt with a screen reader, you should turn on the screen reader’s terminal mode. This will automatically read new text as it appears. NVDA users can toggle this mode using NVDA+5, while JAWS users should use JAWS+S. For more information on Terminal Mode, check your screen reader’s documentation.

After starting the DOS Prompt, change the current directory to the Arduino installation directory which you noted during installation. This will save you a lot of extra typing.

Change the current directory by typing:
Cd ArduinoDirectory

Where ArduinoDirectory is the path where you installed the IDE. If you installed to the default location, you will need to put the path in double quotes since it contains spaces. For example, I used the default location:
C:\Program Files (x86)\Arduino

Since the path contains spaces, use double quotes around the directory name to let the DOS interpreter know that it all goes together like this:
cd "c:\Program Files (x86)\Arduino"

If you don’t type the directory name correctly, or if you don’t use quotes properly, the DOS interpreter will complain. If you type it correctly, the new prompt (the line of text which lets you know that it’s ready for the next command) will be the name of the Arduino directory – in my case, c:\Program Files (x86)\Arduino.

To configure the Arduino IDE from the command line, use Arduino_debug.exe, not Arduino.exe itself. This means that all of the commands we will be typing for things like Arduino configuration or uploading will begin with Arduino_debug, followed by additional command elements called command line arguments. No, we’re not being obstreperous, that’s just what they’re called.

The following sections describe how to set two important Arduino preferences: the com port to which your Arduino board is connected, and the particular Arduino board you are using.

A Few Notes on Error Messages and GUI Pitfalls

Unless you have correctly installed the Java Access Bridge, the Graphical User Interface (GUI) of the Arduino IDE is mostly inaccessible using a screen reader, but a few bits of information do get through. Window names are about the only thing readable by NVDA or JAWS. When working with the command line interface, you may get error messages, warnings, and other unreadable GUI windows that pop up. In the case of error messages and warnings, you can simply dismiss them by hitting Return or Escape.

You may also accidentally launch the Arduino editor if typos make it seem like you are trying to start a new sketch. In this case, a warning will be followed by an editor window which opens with the name of a new sketch based on the current date. You can dismiss this window with Alt+F4, provided that you haven’t accidentally typed anything into the editore window. Otherwise, the IDE will put up an additional unreadable dialog asking if you want to save your changes to the sketch. You don’t, so simply hit Alt+N to select the No button and return to the DOS Prompt window.

Setting the Arduino IDE COM Port Preference

First let’s set the port to which the Arduino is connected (e.g., COM 5). The Arduino connects by USB, but Windows sets up a serial connection through that USB port which emulates a COM port. The COM port is used for uploading code, sending commands, and monitoring output with a terminal program.

After connecting your board to your computer with a USB cable, you can check your Windows Device Manager under USB ports to find out what COM port the Arduino is using. If the Arduino is connected, it should appear in the Device Manager Device list under USB along with the name of the COM port to which it is connected.

Note: The COM port number may change from session to session depending on the physical USB port you use and what other serial communications are active over USB or Bluetooth at any given time. When in doubt, check the device manager again to verify the current COM port being used by your Arduino board. In practice, it’s a good idea to always use the same physical USB port when connecting your Arduino to your development computer.

You can set the COM port used by the Arduino IDE with the following command at the DOS prompt:
arduino_debug --port comPort --save-prefs

Where comPort is actually the COM port you found in the Device Manager. The --save-prefs switch specifies that you want that port value to be saved in the preferences file and used by default. For example, my Arduino board usually ends up on COM5. To set my default Arduino port to COM5, I type:
arduino_debug --port com5 --save-prefs

If the setting change is successful, you will get a few lines of output in the DOS Prompt window saying things like, “Loading configuration…” and “Loading packages…”. If the command is unsuccessful, You will get unreadable error boxes from the Java-based IDE. In this case, just hit Return to dismiss them. If you mistype the command, or if something is wrong, you may also get error messages in your DOS Prompt window. These messages may be helpful in figuring out what is wrong. Use your screen reader review commands to see if you can infer anything useful. Often, typos are the culprit…

Setting the Arduino Board Preference

After successfully setting the communication port, it is time to tell the IDE what Arduino board you are using. This is done with the --board argument followed by a special package:arch:board parameter. Check the documentation associated with your particular board for the right parameter to use here. For example, to configure your IDE for an Arduino Uno board, you would type:
arduino_debug --board arduino:avr:uno --save-prefs

If this parameter change is accepted you’ll get a few lines of innocuous output in the DOS Prompt window without any dialog or error boxes. If something is wrong, the IDE will throw up unreadable error boxes which need to be dismissed with Enter or Escape. Check the DOS Prompt window for meaningful text error messages before trying again.

Verifying Preferences

You can verify your settings by asking the IDE to tell you what the current port and board are using the --get-pref argument. To get the port preference, type:
arduino_debug --get-pref serial.port

To get the board preference, type:
arduino_debug --get-pref board

As usual, typos or incorrect commands will yield unreadable error boxes, while well-formed and correct commands will report the current COM port or board in the DOS Prompt window.

Note: you can get a massive list of all of the current parameters of the Arduino IDE by typing:
arduino_debug --get-pref

That's it -- you're done with the setup. Now you’re ready to start uploading sketches to your board, but that’s another article!


I’d like to give a special shout out to John Schimmel of
DIYAbility in New York City
who helped me find a good deal of the information in this and subsequent posts. He also held my hand and shouted encouragement for my first few Arduino baby steps. Thanks also to all the blind and sighted Makers who support this project – Chancey Fleet, Ben Einstein, Laura Eberly, Jim Barbour, Brian Buhrow, Erin Lauredsen, Will Butler, Bryan Bashin, and others. Blind Arduino is a project of
Smith-Kettlewell and
LightHouse Labs.