GLOBAL SALES

    The easiest way to develop and debug your Dash programs is with a serial connection to a computer. You can use two-way serial communication to print diagnostic information or to send commands to the Dash without wiring physical components such as buttons.

    Setting up a serial connection requires two parts:

    • Physically connecting the Dash to your computer, with USB or UART pins on the Dash
    • Software on your computer for interfacing with the serial connection

    The easiest method is to use a USB connection with the Arduino IDE’s serial monitor. Since there may be cases where these tools aren’t available, this guide also describes some alternatives.

    Connect the Dash to your computer with a USB cable. In the menu bar go to Tools -> Port and select the appropriate serial or USB port. Typically the ports are named as follows according to your operating system:

    • WindowsCOMx
    • MacOS/dev/cu.usbmodemxxxx
    • Linux/dev/ttyUSBx or /dev/ttyACMx

    where x is a system-specific identifier. If you are still unsure of which port to use, disconnect the Dash and check which port disappears from the list. Then re-connect the Dash and select that port.

    Note

    If you're on Windows 8.1 or earlier and no port shows up when plugging in the Dash, see our Windows guide for driver installation instructions.

    Then, open the Serial Monitor from any Arduino editor window.

    Opening the Serial Monitor

    At the top of the Serial Monitor is an input box for sending text to the Dash. Under that is a larger box which displays text received from the Dash. At the bottom of the window are settings for the serial connection.

    Arduino Serial Monitor

    Typically you should set Line ending to Newline so that sending a message automatically appends a newline (\n) character. Baud rate must match the rate configured in the Dash program. Most example programs use 9600 baud.

    USB-to-TTL Converter

    Instead of using the Dash’s onboard Micro USB port, you may communicate over the TTL UART interface through a USB-to-TTL converter. You may want to use this method if you plan to interface with another device over TTL and want to verify that you can communicate over those pins.

    You must use the Serial2 interface (UART pins RX2 and TX2) because the Dash uses Serial1 for communicating with the Hologram Cloud. The appropriate pins are as follows:

    • RX2: Pin L06
    • TX2: Pin L08

    Using header hook-up wire,

    • Connect the Dash’s GND pin to the TTL converter’s GND pin
    • Connect the Dash’s RX2 (L06) pin to the TTL converter’s Tx (or TXD) pin
    • Connect the Dash’s TX2 (L08) pin to the TTL converter’s Rx (or RXI) pin
    • Connect the TTL converter to the computer using a USB cable

    Note that the Dash’s receiving (RX) pin connects to the converter’s transmitting (TX) pin, and vice versa. If you don’t see data when you expect to, try swapping the two connections. Sometimes TTL converters can label pins in reverse!

    The completed connection should look something like:

    TTL connection on Dash Pro

    With the pre-loaded program, the Dash will forward any messages sent from the UART interface to the Hologram Cloud. When writing your own programs, make sure to use the Serial2 interface in your Arduino code. This example illustrates sending and receiving data over different Serial interfaces.

    Alternate Terminal Emulators

    Regardless of how you physically connect the Dash to your PC, it will be accessible as a generic USB/Serial device. This means you can use any serial interface application (also called terminal emulator) you wish to send/receive data. The Arduino IDE’s serial monitor is cross-platform and is the easiest to set up. More advanced users may wish to use an alternative terminal emulator:

    Screen

    Screen is a command line Linux/Unix application that can interface with attached serial devices. Screen is installed by default on MacOS and most Linux distributions.

    First, find the device file corresponding to your Dash:

    MacOS:

    ls /dev/cu.usbmodem*
    

    Linux:

    ls /dev/ttyUSB*
    ls /dev/ttyACM*
    

    If there’s more than one device listed, you can disconnect the Dash and re-run the command to see which device disappears from the list.

    Open a screen session at the default baud rate of 9600, e.g.:

    screen /dev/ttyUSB4
    

    Note

    On Linux, you must ensure your user has proper permissions to access the serial interface. On Debian-based distributions, run: ``sudo adduser `whoami` dialout``

    The terminal will display any data sent from the Dash. The Dash will receive any text that you type into the terminal.

    To close the session and quit screen, type Ctrl-A followed by k. Then type ‘y’ at the prompt to confirm.

    PuTTY

    PuTTY is a terminal emulator for Windows. Download the latest version here.

    Determine the COM port associated with your Dash: Open the device manager and expand the Ports (COM & LPT) section. You should see a USB Serial Port entry with a COM identifier, e.g. COM3. Note this identifier.

    Open PuTTY and configure the connection as follows:

    • Connection type: Serial
    • Serial line: COM identifier as noted above
    • Speed: 9600

    Click Open to establish a connection to the Dash. The terminal will display any data sent from the Dash. The Dash will receive any text that you type into the terminal.

    Raspberry Pi and Other Embedded PCs

    You can use the Dash’s default program to send messages from an embedded PC (or any other serial device) to the Hologram Cloud.

    On the Linux device, add Hologram’s udev rules to enable the proper permissions and to disable ModemManager from taking over the device:

    sudo wget -O /etc/udev/rules.d/85-hologram.rules \
      https://raw.githubusercontent.com/hologram-io/hologram-dash-arduino-integration/master/85-hologram.rules
    

    Using a micro USB cable, connect the Dash to one of the USB ports on your embedded PC. The Dash’s serial interface will be available as /dev/ttyACM0.

    Send a test message from the command line:

    echo "Hello, Hologram!" > /dev/ttyACM0
    

    You can also use a serial library in your programming language of choice to communicate with the device. Here’s a simple Python example:

    import serial
    import sys
    
    try:
       port = serial.Serial("/dev/ttyACM0", baudrate=9600, timeout=1)
    except:
       print("FAIL, No USB Serial connected")
       sys.exit(1)
    
    if not port.isOpen():
       self.log("Serial port wasn't opened")
       sys.exit(1)
    
    port.write("TEST MESSAGE\n")