Getting started with Arduino Yun and Autobahn

, Tobias Oberstein

Real-time charting in HTML5 of sensor values from Arduino Yun over WebSocket with Autobahn.

Preface

Last update on 2014/10/10: Code for this tutorial has been migrated to WAMP2 and tested to work with the latest AutobahnPython (0.9.1) and AutobahnJS (0.9.5). You can find all the code here. The tutorial was simplified and revised.

Introduction

The Arduino Yun is a small embedded computer which can be used as a flexible platform for all kinds of hardware projects:

Arduino Yun
Arduino Yun

The Yun actually is 2 computers in one:

  • a tiny 8-Bit AVR MCU (ATmega32u4 with 32kB Flash and 2.5kB RAM running at 16MHz)
  • a small 32-Bit MIPS CPU (Atheros AR9331 with 16MB Flash and 64MB RAM running at 400MHz)

The MCU runs in hard real-time: you can use it to e.g. directly control servo motors or interface to sensors. The CPU on the other hand is powered by an embedded Linux (Linino) that does not run in hard real-time, but is capable of doing full flavored TCP/IP networking over Ethernet and Wifi. The MCU and the CPU are connected via a serial interface.

Now, while the Arduino Yun (like all Arduinos) already allows you to create awesome hardware oriented projects, wouldn't it be great if you could connect your Arduino Yun to other devices, browsers or mobile apps, communicating in (soft) real-time over the Web?

Enter Autobahn, an open-source (soft) real-time communication framework for Web, Mobile and the Internet of Things:

Autobahn WebSocket

The Autobahn project provides open-source implementations of the WebSocket and WAMP protocols. WebSocket allows bidirectional real-time messaging on the Web and WAMP adds asynchronous Remote Procedure Calls and Publish & Subscribe on top of WebSocket.

Here is an example of what you can do with Arduino Yun and Autobahn:

  • stream sensor readings in real-time from the Arduino Yun via WebSocket to HTML5 browsers on desktop and mobile
  • control LEDs directly from your browser (again in real-time with very small latency)

Arduino Yun Real-time Charting over WebSocket with Autobahn

The demo shows a shield on the Yun with 2 potis, 3 LEDs and 2 buttons, which are controlled from a simple sketch running on the Arduino. The sketch communicates over serial with Autobahn running on the Linux side of the Yun. And Autobahn in turn runs as a bridge that shuffles data from/to serial and to WebSocket/WAMP clients (here, Chrome running on desktop and on Nexus 4) connecting to Autobahn over Wifi.

What we cover

We show how to do a project like the above step-by-step. Everything. In detail.

This is the first part of a series of blog posts which will get you up and running with Arduino Yun and Autobahn. Further posts will cover how to use Crossbar.io, an open-source multi-protocol application router that builds on Autobahn and allows to create sophisticated distributed systems and applications.

Contents:

  • System recovery
  • Network configuration
  • Software installation
  • Running the demo

What you need

To follow this tutorial you'll need

  • an Arduino Yun
  • a micro SD card (at least 128MB, I use a 1GB card for 5 Euros)
  • 2 Potis and 1 LED wired to the Yun

System Recovery

Should anything go wrong with your experiments here, don't worry - the Yun includes mechanisms to:

  • reset Wifi network configuration to factory default
  • restore Linux system image to factory default

The relevant button to perform both of these functions is called "Wifi Reset button" in the Yun documentation and is located here:

Arduino Yun
Arduino Wifi-Reset (and Linux-Restore) Button
  1. Pressing the Wifi Reset button for >5s (but less than 30s) and then releasing will reset the Wifi configuration to factory default

  2. Pressing the Wifi Reset button for >30s and then releasing will restore the Linux system image to factory default

Both functions will also reboot the Yun.

Network Configuration

The Yun has two network interfaces:

  • Ethernet (100Mb)
  • Wifi (bgn)

where each network interface has it's own MAC address.

Wifi

When the Arduino Yun is first powered on, the Wifi will be starting in AP-Mode ("Access Point Mode") and the Yun creates a new wireless network on the IP range

192.168.240.0/24

When you scan for Wifi networks, you should see a new network with a SSID as

Arduino Yun-XXXXXXXXXXXX

where XXXXXXXXXXXX is the MAC address of the Yun's Wifi interface:

Arduino Yun
Arduino Yun Wifi Network in AP Mode

This is the factory default, and when you reset the Wifi configuration, it will be the recovered again.

Note: The ethernet interface has a different MAC address - see below.

You can access the Web configuration interface of your Yun by connecting e.g. your notebook to the above Wifi network and then open the following URL in your browser

http://192.168.240.1

The default administrator password is arduino. You might want to change that (which you can do from the Web configuration interface).

Ethernet

The ethernet interface on the Yun is configured by default to get an IP address via DHCP (as is the Wifi interface in client mode) from a DHCP server on your network (such as your home router).

When you plug in the ethernet, the Yun ethernet interface should get assigned an IP automatically which you can verify from the Web interface:

Arduino Yun network interface status
Arduino Yun network interface status

Wifi Client Mode

When your Yun is connected via Ethernet to your network, the Yun will be able to connect to the public Internet via the default router on your network (your home router).

However, if you plan to have you Yun connecting to the Internet without an ethernet cable connected, you will need to reconfigure the Yun's Wifi to run in Client Mode and have the Yun connect to your router via Wifi as a client, so it can call out to the Internet.

Arduino Yun Wifi Client Mode
Arduino Yun Wifi Client Mode

After reconfiguration, the Yun will reboot, and you now should see both network interfaces on your main LAN and with IP addresses assigned from your router:

Both Yun network interfaces on LAN
Both Yun network interfaces on LAN

Doing the above, the Yun will no longer function as a Wifi access point to which others Wifi clients could connect. As long as the Yuns IP is known to other peers on your network, those peers will however still be able to connect on the TCP/IP level to anything running as a server on your Yun.

Static DHCP

When your Yun gets IP addresses for its ethernet and Wifi interfaces, your router will usually select free unassigned IP addresses randomly (from its IP range) - but these IP addresses can change from time to time (or across reboots of your router).

Some home routers or advanced router OSs such as OpenWRT and DD-WRT allow to configured DHCP to assign IP addresses to certain devices statically (called "static DHCP"). That means the device will always get the same IP address.

Having you Yun get static IPs via DHCP is useful, since e.g. to login from outside into your Yun via SSH will always work with the same IP.

Here is how static DHCP configuration looks on DD-WRT:

Both Yun network interfaces on LAN
Configuration of static DHCP for both Yun interfaces

And here is how the status page for LAN IPs looks on DD-WRT:

Both Yun network interfaces on LAN
Network status of both Yun interfaces (with assigned IP addresses)

SSH

Now that you have networking running for your Yun (either ethernet, Wifi or both), the next thing is to SSH into your Yun. This will allow you to do further software setup and advanced system configuration from a root shell.

The default password for root is arduino.

Here is how that looks:

$ ssh -l root 192.168.1.150
The authenticity of host '192.168.1.150 (192.168.1.150)' can't be established.
RSA key fingerprint is f9:e0:1e:bd:bb:f9:e1:33:5b:c7:5d:75:da:2c:20:b1.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '192.168.1.150' (RSA) to the list of known hosts.
root@192.168.1.150's password:


BusyBox v1.19.4 (2013-08-07 16:16:02 CEST) built-in shell (ash)
Enter 'help' for a list of built-in commands.

      ___                   ___                       ___           ___
     /\__\      ___        /\__\          ___        /\__\         /\  \
    /:/  /     /\  \      /::|  |        /\  \      /::|  |       /::\  \
   /:/  /      \:\  \    /:|:|  |        \:\  \    /:|:|  |      /:/\:\  \
  /:/  /       /::\__\  /:/|:|  |__      /::\__\  /:/|:|  |__   /:/  \:\  \
 /:/__/     __/:/\/__/ /:/ |:| /\__\  __/:/\/__/ /:/ |:| /\__\ /:/__/ \:\__\
 \:\  \    /\/:/  /    \/__|:|/:/  / /\/:/  /    \/__|:|/:/  / \:\  \ /:/  /
  \:\  \   \::/__/         |:/:/  /  \::/__/         |:/:/  /   \:\  /:/  /
   \:\  \   \:\__\         |::/  /    \:\__\         |::/  /     \:\/:/  /
    \:\__\   \/__/         /:/  /      \/__/         /:/  /       \::/  /
     \/__/                 \/__/                     \/__/         \/__/

            _______                     ________        __
           |       |.-----.-----.-----.|  |  |  |.----.|  |_
           |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
           |_______||   __|_____|__|__||________||__|  |____|
                    |__| W I R E L E S S   F R E E D O M

root@Arduino:~#

To change the password for root, type passwd.

I can't give an introduction to SSH here, but personally, on Windows, I use both Putty and the OpenSSH client that comes integrated with Git for Windows (and OpenSSH on Unix-like systems where it is most often installed by default already).

Public Key Authentication

Now, retyping your password each time you log in gets old fast. Public key based authentication for SSH allows you to do password-less, but nevertheless secure logins.

This isn't the place to give an introduction to SSH and public key authentication, however you should have little problems finding tutorials and information on the net. I will only cover stuff that is "unusual" on the Yun compared to a commonly seen Unix.

The Linino/OpenWRT Linux on the Yun does use Dropbear for SSH support (both client and server) - this is a different software package from usual Linux distributions and Unix systems (which is OpenSSHd).

One difference is that to enable public key based authentication for root, the authorized public keys need to be added to the following file (and not the usual /root/.ssh/authorized_keys):

vi /etc/dropbear/authorized_keys
chmod 0600 /etc/dropbear/authorized_keys

A complete tutorial for setting up public key based authentication on OpenWRT can be found here.

SSHFS

Another thing you probably want to do: mount the Yun's filesystem on your desktop via SSH.

Why is that? Mounting over SSH allows you to edit files on the Yun using your favorite editor directly on your desktop. So you don't need to fiddle with vi and such inside a shell;) E.g. I use the awesome SublimeText editor on Windows. Yeah, you probably prefer something else - and that is fine, since it will work too.

This magic works via SFTP (secure FTP), which is a FTP-like protocol that runs over SSH. On the Yun side, you'll need to have the SFTP package installed, login via SSH as root and do:

opkg update
opkg install openssh-sftp-server

Now, on Windows, I recommend Win-SSHFS which you can download from here. It's open-source and installs without hassles. Just "Ok-Install" everything.

You'll get a small Puffy-fish icon in your quicklaunch bar, double click and configure a new virtual drive:

Arduino Yun
Yun's root filesystem mounted as Windows drive "I:"

When done and mounted, a new drive appears on your Windows machine, which maps to the remote Yun's root filesystem:

Arduino Yun
Yun's root filesystem mounted as a virtual drive

On Mac OSX, there is a nice tutorial here that walks you through setting things up with FUSE for OSX.

On Ubuntu, you can use Nautilus or the command line.

With SFTP set up, you now can simply open, edit, create, copy, delete and move files conveniently from your desktop. Which can often be more comfortable than doing everything via command line SSH (and SCP).

Software Installation

The CPU on the Yun runs Linino, a Linux distribution derived from OpenWRT. OpenWRT was originally created and is mainly used as an open-source OS for use with routers like for example the Linksys WRT54G or Asus RT-AC66U.

Autobahn is a Python-based framework. Luckily, the Linux system on the Yun already includes Python 2.7.3:

root@Arduino:~# uname -a
Linux Arduino 3.8.3 #8 Mon Aug 19 16:22:39 CEST 2013 mips GNU/Linux
root@Arduino:~# python -V
Python 2.7.3
root@Arduino:~# python
Python 2.7.3 (default, Aug  8 2013, 22:36:42)
[GCC 4.6.4 20121210 (prerelease)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>

However, we need a few more bits. I'll guide you through installation.

Expanding Disk Space

The / filesystem on the Yun only has 8MB space in total (the other 8MB of the total 16MB Flash are used for system recovery):

root@Arduino:~# df -h
Filesystem                Size      Used Available Use% Mounted on
rootfs                    7.5M    392.0K      7.1M   5% /
/dev/root                 7.0M      7.0M         0 100% /rom
tmpfs                    29.9M    344.0K     29.5M   1% /tmp
tmpfs                   512.0K         0    512.0K   0% /dev
/dev/mtdblock3            7.5M    392.0K      7.1M   5% /overlay
overlayfs:/overlay        7.5M    392.0K      7.1M   5% /

The free space on / isn't enough for the software we will use. And we also want to have space for local data storage.

Hence we will create a new filesystem on a micro SD card which we can use for both programs and data and mount that filesystem as an overlay on top of the root directory (usually, this is called an "extroot").

Please follow the instructions here to do that.

This is how free space looks after exanding (using a 1GB SD card):

root@Arduino:~# df -h
Filesystem                Size      Used Available Use% Mounted on
rootfs                  816.7M      3.0M    771.4M   0% /
/dev/root                 7.0M      7.0M         0 100% /rom
tmpfs                    29.9M    104.0K     29.8M   0% /tmp
tmpfs                   512.0K         0    512.0K   0% /dev
/dev/sda2               816.7M      3.0M    771.4M   0% /overlay
overlayfs:/overlay      816.7M      3.0M    771.4M   0% /
/dev/sda1                99.8M      4.0K     99.8M   0% /mnt/sda1

Installing Base Packages

The Arduino Yun uses a package system based on the OpenWRT opkg tool which can be used to install binary packages from the repository here.

The first thing to do should be to update the package list cached on the Yun (you need to redo that on every new login since it does not persist). Login to your Yun over SSH and do:

opkg update

Now install a few packages we'll need:

opkg install bzip2
opkg install unzip
opkg install tar
opkg install wget
opkg install fdisk
opkg install e2fsprogs
opkg install openssh-sftp-server
opkg install pyopenssl
opkg install python-openssl
opkg install python-crypto
opkg install python-bzip2
opkg install python-sqlite3
opkg install python-ncurses

This might take some time, but the packages are installed into the / root filesystem and will be permanently available from now on.

Installing Setuptools

Install Setuptools by doing:

cd /root
wget --no-check-certificate https://pypi.python.org/packages/source/s/setuptools/setuptools-6.0.2.tar.gz
tar xvzf setuptools-6.0.2.tar.gz
cd setuptools-6.0.2
python setup.py install

Note: Yun does not come with certificates installed, hence we use the option --no-check-certificate. This means the server certificate of the site from which we download is not checked. You can do that, but we skip it for now.

Installing Twisted

For low-level networking, Autobahn relies on Twisted, an asynchronous Python framework for high-performance, scalable networking.

We need to install Twisted from sources, since Twisted by default wants to build a few Python binary extensions, which won't work since there is no C compiler installed on the Yun. Those Twisted binary extensions however are not really required, so we will skip those during the source install.

Twisted depends on zope.interface - let's install that via easy_install:

easy_install zope.interface

Now download the Twisted source archive

cd /root
wget --no-check-certificate https://pypi.python.org/packages/source/T/Twisted/Twisted-14.0.2.tar.bz2

and unpack the archive

tar xvjf Twisted-14.0.2.tar.bz2
cd Twisted-14.0.2

Now edit setup.py and comment out line 63 (see here, here, here and here):

#        conditionalExtensions=getExtensions(),

Note: The number of the line to be commented (L63) might change with future Twisted versions. The relevant thing is to comment the conditionalExtensions=.. statement.

Then build and install Twisted:

python setup.py install

This will take a long time. Be patient;) The Yun doesn't have a lot of steam and we are installing onto a micro SD card, which means low filesystem performance on top.

Installing pySerial and Autobahn

Since we want to talk to the MCU from the main CPU via serial, install Python serial support via pySerial:

easy_install pyserial

And finally, for WebSocket/WAMP protocol support install Autobahn:

easy_install autobahn

To test that Autobahn has been installed correctly, you can do

root@Arduino:~# python
Python 2.7.3 (default, Aug  8 2013, 22:36:42)
[GCC 4.6.4 20121210 (prerelease)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import autobahn
>>> autobahn.__version__
'0.9.1'
>>>

Disable Console on Serial

We are using the serial connection between the MCU and the CPU. By default, there is a console attached on the Linux side to the serial, and we need to disable that.

Edit the file /etc/inittab and comment the following line (by preceding it with #):

# ttyATH0::askfirst:/bin/ash --login

The Linux SoC (CPU) and the Atmel MCU are connected via a UART (a serial connection) which maps to the device /dev/ttyATH0 on the Linux side and the serial stream class Serial1 on the Arduino side. The default inittab entry on the Linux side will start a shell connected to that serial port when Linux boots. Then, when your sketch starts the Arduino Yun bridge library (by doing Bridge.begin()), the bridge library writes a command to the serial that will in turn start a script on the Linux side which then connects to the serial port. That Linux script is essentially the Linux-side part of the Yun bridge library and will keep on running regardless of wether you reload a new sketch to the MCU or reset the MCU. It will keep on running until you reset the CPU or reboot Linux (or manually kill the script). However, as long as there is a script running and using the serial port, we cannot use the serial for our purposes. The commenting of the inittab line will disable starting a shell on the serial port altogether in the first place. This means we can use the serial port for our stuff, but it also means you won't be able to use the Yun brigde library anymore.

and reboot Linux:

reboot

Be patient, a reboot (either via the reboot command like above, or by doing a cold boot via power cycling or pressing the "Yun RST" button) can take 60-90s.

Running the Demo

Download the Demo

The full demo code resides under examples/twisted/wamp/app/serial2ws in the AutobahnPython Git repository here.

You can download an archive containing a snapshot of the complete AutobahnPython repository to your PC:

Alternatively, you can use Git to clone the repository:

git clone git@github.com:tavendo/AutobahnPython.git

Using Git allows you to easily update to the latest code later by doing

cd AutobahnPython
git pull

Compile the Demo sketch

Compile and upload the sketch to your Yun:

/examples/twisted/wamp/app/serial2ws/serial2ws.ino

You will need to adjust pins for the hardware you have. The demo uses 2 potis and 1 LED.

Run the Demo bridge

To run the demo on your Yun, you will need to copy the following 4 files to the Yun Linux

serial2ws.py
index.html
smoothie.js
autobahn.min.js

From your Yun, do

cd /root
wget --no-check-certificate \
   https://raw.githubusercontent.com/tavendo/AutobahnPython/master/examples/twisted/wamp/app/serial2ws/serial2ws.py \
   https://raw.githubusercontent.com/tavendo/AutobahnPython/master/examples/twisted/wamp/app/serial2ws/index.html \
   https://raw.githubusercontent.com/tavendo/AutobahnPython/master/examples/twisted/wamp/app/serial2ws/smoothie.js \
   https://raw.githubusercontent.com/tavendo/AutobahnPython/master/examples/twisted/wamp/app/serial2ws/autobahn.min.js

Alternatively, to copy over the files, you can use the method with the / directory mounted over SFTP to your desktop or by using scp:

cd AutobahnPython/examples/twisted/wamp/app/serial2ws
scp serial2ws.py index.html smoothie.js autobahn.min.js root@192.168.1.150:/root

Here and in the following, replace 192.168.1.150 with the IP address of your Yun.

Now run the bridge:

python serial2ws.py --debug --port /dev/ttyATH0

Startup of the demo takes some time. The log output should look like

root@Arduino:~# python serial2ws.py --debug --port /dev/ttyATH0
2014-10-10 13:15:13+0000 [-] Log opened.
2014-10-10 13:15:14+0000 [-] Using Twisted reactor <class 'twisted.internet.epollreactor.EPollReactor'>
2014-10-10 13:15:33+0000 [-] Site starting on 8000
2014-10-10 13:15:33+0000 [-] Starting factory <twisted.web.server.Site instance at 0x76bbf3f0>
2014-10-10 13:15:33+0000 [-] WampWebSocketServerFactory starting on 8080
2014-10-10 13:15:33+0000 [-] Starting factory <autobahn.twisted.websocket.WampWebSocketServerFactory instance at 0x76bc6378>
2014-10-10 13:15:36+0000 [-] Starting factory <autobahn.twisted.websocket.WampWebSocketClientFactory instance at 0x76bec058>
2014-10-10 13:15:37+0000 [WampWebSocketClientProtocol,client] MyComponent ready! Configuration: {'debug': True, 'baudrate': 9600, 'port': '/dev/ttyATH0'}
2014-10-10 13:15:37+0000 [WampWebSocketClientProtocol,client] About to open serial port /dev/ttyATH0 [9600 baud] ..
2014-10-10 13:15:37+0000 [WampWebSocketClientProtocol,client] Serial port connected.

Now open the page http://192.168.1.150:8000 in your browser.

If everything works, you should see nicely rendered graphs with real-time readings from the 2 Potis and also have 2 buttons to control the LED like in the video above. Hurray;)

Command Line Options

The bridge has a number of command line options. You can get help by doing:

root@Arduino:~/# python serial2ws.py --help
usage: serial2ws.py [-h] [-d]
                    [--baudrate {300,1200,2400,4800,9600,19200,57600,115200}]
                    [--port PORT] [--web WEB] [--router ROUTER]

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           Enable debug output.
  --baudrate {300,1200,2400,4800,9600,19200,57600,115200}
                        Serial port baudrate.
  --port PORT           Serial port to use (e.g. 3 for a COM port on Windows,
                        /dev/ttyATH0 for Arduino Yun, /dev/ttyACM0 for Serial-
                        over-USB on RaspberryPi.
  --web WEB             Web port to use for embedded Web server. Use 0 to
                        disable.
  --router ROUTER       If given, connect to this WAMP router. Else run an
                        embedded router on 8080.

Outlook

With the pieces above you already can do some nice projects. You can have a single Yun communicate with browsers in real-time. In both directions.

However, there are some questions that immediately come to mind:

  1. What if the Yun runs on a private network (behind NAT), and you want to connect from your browser running somewhere else in the world?
  2. What about multiple Yuns? On one network, or different networks?
  3. What about hooking up your Yun to backend components running in a data center? For example, you might want to store your sensor data in a database.

We are preparing a follow up post that will address these scenarios by connecting the bridge component that runs on the Yun to Crossbar.io (a WAMP router) that can run anywhere.

Happy tinkering;)

/Tobias

Resources

  1. Autobahn
  2. OpenWRT
  3. Arduino Yun
  4. Expanding Disk Space
  5. Running OpenWRT
  6. Python

Find out how to create component-based, real-time apps for the Web, mobile and IoT in less time and with less complexity using

Crossbar.io name

Crossbar.io is an open-source Unified Application Router created and supported by Tavendo

Learn more

About

Tavendo provides open-source middleware that helps developers create next-gen applications in less time and with less complexity.

We are authors and maintainers of WAMP (Web Application Messaging Protocol), Crossbar.io (Unified Application Router) and Autobahn (Real-time Web Framework).

us on Twitter

Stay Informed

Sign up for our newsletter to stay informed of new product releases and features:

Professional Services

Tavendo offers consulting, support and custom development for Crossbar.io and Autobahn based solutions.

Get in contact and send us an Email describing your project, issue or question.

Recent posts

Atom Feed

Search this Site