Saturday, January 2, 2016

Arduino Setup and Accessibility Tips for Windows

Background


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.

Installing 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 graphical user interface of the Arduino IDE is not accessible on Windows using a screen reader. It 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 are a little tricky to make accessible for screen readers, and most, like the Arduino IDE graphical user interface, are not accessible. Luckily, the Arduino IDE also includes a command line interface that lets a blind user access most features from a Windows DOS Prompt. More about that in the next section. For now,
Just 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. We then describe how to save these preferences so that the IDE remembers the settings next time.

A Few Notes on Error Messages and GUI Pitfalls

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

Where comPort is actually the COM port you found in the Device Manager. For example, my Arduino board usually ends up on COM5. To set my port to COM5, I type:
Arduino_debug --port com5

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

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

Saving Arduino IDE Preferences

Once you’ve set the Arduino IDE preferences as you like, you can save them by typing:
Arduino_debug --save-prefs

If the command is accepted you should see a confirmation message in the DOS Prompt window. Otherwise you will get the usual unreadable error boxes and need to try again.

Once the preferences are saved, the IDE will remember what board and port you want to use.

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!

Acknowledgements


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.

13 comments:

  1. Incidentally, if you're going to be doing a lot of command line arduino development, you may want to set up a shortcut on your desktop or elsewhere that opens a command prompt directly into your arduino directory.

    To do this, use the Windows Explorer to open the directory c:\windows\system32 and select the file CMD.EXE. Then use your context menu (right-click) to make a shortcut. Windows will offer to put the new shortcut on your desktop and you should accept.

    Now navigate to the desktop (for example with Windows+M) and select the new shortcut. Open the properties (again with the context menu) and in the "Start In:" field, type the name of your arduino directory -- for example, "c:\program files (x86)\arduino", and hit Return to save the properties.

    Finally, you can edit the name of the shortcut (with F2) to be something like "Arduino cmd", which will then be the name of the window when you open it.

    Just thought I'd mention it because this is how I've got it set up on my machine and it's pretty convenient.

    ReplyDelete
  2. Hi,
    Thanks for the great descriptions. In the past, I have had success in using visual studio to develop on the Arduino. It makes debugging easier. There used to be a library one could install and get an Arduino sketch as a project type. I do not know if this is still possible in visual studio 2015 community addition.

    ReplyDelete
  3. Thanks, Pranav! Can you say a little more about the version of VS you've used and what screen reader you've had success with? I'm not a VS user, so would really appreciate some links to resources for getting up and running with it.
    Thanks!

    ReplyDelete
  4. Hi Joshua,
    only a note: recently, I casually opened arduino.exe (IDE version 1.6.6), even if I knew the editor bad accessibility, , and... WOW, editor seems accessible now! :)
    I must organize again the board, driver and so on, so I not tested other yet, but the news is very welcome, anyway. Obviously, Java (8) on my system (Windows 7 64-bit) is installed (32 and 64-bit versions) and correctly configured, and I verified with NVDA.
    Then, if you interested, I saw a project to manage Arduino projects via terminal, called Ino:
    http://inotool.org/
    it's originally for Linux and Mac terminal only, but I would be able to run it in Windows, manually linking it to Arduino IDE path. However, as above, I must test it in more detail.
    Bye and good luck with this blog! :)

    ReplyDelete
  5. This is extremely interesting. I am unable to duplicate your success using Arduino 1.6.7, NVDA, and Windows 8... Is it possible your .INO files are actually associated with another (accessible) editor and you simply thought it was the Arduino IDE by accident? Believe me, I would love for you to be right about this, but I can't make it happen, even with all the latest Java installed and the "Access Bridge" enabled. What version of Arduino are you using?

    ReplyDelete
    Replies
    1. Hi Joshua,
      I just downloaded Arduino IDE 1.6.7. And yes, launching arduino.exe, the editor works properly, for me. Do you have checked your Access Bridge support launching javacpl from Windows Run? In alternative, try to navigate to arduino-1.6.7\java\bin and run jabswitch -enable from this path (I cannot exclude I did it in the past, even if not in this case). Ah, I use the IDE zip package, not installer.

      Delete
    2. Hi, Album!
      With the Java Access Bridge installed and activated I can get access to menus and some dialogs in the Arduino IDE (V 1.6.8), but still I cannot edit or read the text of a sketch.

      Do you think that installing from the ZIP rather than the installer could have an impact on this?

      Delete
  6. Sorry for not reading your comment more closely -- I see now that you're using Arduino 1.6.6.

    Also, I am aware of the command-line tool INO, but it is no longer supported, and I believe never was on Windows.

    The INO code was forked to become Arturo:
    http://32bits.io/Arturo/

    Arturo is a Python command-line tool for compiling and uploading Arduino sketches, but does not work with Arduino later than 1.6.2. Still, it may be worth investigating.

    Since the Arduino IDE now has decent support for command line use, these third-party tools may no longer be as necessary.

    ReplyDelete
  7. FYI, much to my amazement, the Arduino IDE (1.6.8) seems to be accessible on the Mac with VoiceOver.

    ReplyDelete
  8. There is a capital S in the article that makes this command not work:

    arduino_debug --get-pref Serial.port

    It should be:

    serial.port

    Seems the command line is case sensitive.

    When I run
    arduino_debug --save-prefs

    It opens the ide and I am not sure if it has saved those prefs correctly.

    ReplyDelete
  9. IDE is nearly accessible with orca in linux, but it soon crashes after opening.
    Commandline in linux of course works great.

    ReplyDelete
  10. I am getting some extensive errors when I try and save my prefs. Is there a best practice to get meaning from the "meaningfull" output in the command line?
    example:
    Exception in thread "cc.arduino.packages.discoverers.serial.SerialBoardsLister" java.lang.UnsatisfiedLinkError: C:\Users\David Engebretson\.jssc\windows\jSSC-2.8_x86.dll: %1 is not a valid Win32 application

    ReplyDelete
  11. I think the error might be a red herring. The settings seems to be saved... now to breadboardblind...

    ReplyDelete