Synapse SNAPconnect E12 User Manual

USER GUIDE

SNAPconnect E12

SNAP Enabled Gateway

©2008-2017 Synapse Wireless, All Rights Reserved. All Synapse products are

patent pending. Synapse , the Synapse logo, SNAP, and Portal are all registered trademarks

of Synapse Wireless, Inc.

Doc# 116-081614-030-B001

6723 Odyssey Drive // Huntsville, AL 35806 // [phone] // Synapse-Wireless.com

Disclaimers

Information contained in this manua l is provided in connection with Synapse Wireless products and services and is intended solely to assist its customers.

Synapse reserves the right to make changes at any time and without notice.Synapse assumes no liability whatsoever for the contents of this manual or the

redistribution a s permitted by the foregoing limitedlicense. The terms and conditions governing the sale or use of Synapse products is expressly contained in the

terms and conditions for the sale of those respectiveproducts.

Synapse retains the right to make changes to any product specification at any time without notice or liability to prior users, contributors, or recipients of

redistributed versions of this manual. Errata should be checked on any product referenced.

Synapse and the Synapse logo a re registered trademarks of Synapse Wireless. All other trademarks are the property of their owners.

For further information on any Synapse product or service, contact us at:

Synapse Wireless,Inc.

6723 Odyssey Drive

Huntsville,Alabama 35806

256-852-7888

877-982-7888

256-924-7398 (fax)

www.synapse-wireless.com

License governing any code samples presented in this Manual

Redistribution of code and use in source and binary forms, with or without modification, are permitted provided that it retains the copyright notice, operates only

on SNAP®networks, and the paragraphs below in the documentation and/or other materials are provided with the distribution:

Copyright 2008-2016, Synapse Wireless Inc., All rights Reserved.

Neitherthe na me of Synapse nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written

permission.

This software is provided “AS IS,” without a warranty of a ny kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING

ANY IMPLIEDWARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SYNAPSE AND

ITS LICENSORS SHALLNOT BE LIABLE FOR ANY DAMAGES SUFFERED B Y LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THISSOFTWARE

OR ITS DERIVATIVES. IN NO EVENT WILL SYNAPSE OR ITS LICENSORSBE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT,

SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED ANDREGARDLESSOF THE THEORY OF LIABILITY, ARISING OUT OF

THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SYNAPSE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCHDAMAGES.

Table of Contents

Overview 1

The Device 2

Getting Started 3

Powering the E12 3

Establishing a Serial Connection 3

Mounting the E12 8

E12 Software Specifics 9

Passwords and root Access 9

E12-Specific Software Packages 9

E12 Physical Interfaces 11

E12 LEDs 11

The SNAPModule-Controlled LED 11

The E12 Button 12

Working With the Gateway's SNAPModule 13

Waking the SNAPModule 13

Resetting the SNAPModule 14

Restoring Functionality to an Unresponsive SNAPModule 14

Upgrading the SNAP Module Firmware 15

Accessing the MicroSD Slot 17

Common Linux Operations 18

Editing Linux Files 18

Making Your Software Run at Startup 18

Running a Script to Completion 18

Starting a Service 19

Setting Your E12’s Clock 20

Resetting a Lost User Password 20

Mounting an External Drive 21

Extending the E12 with USB Accessories 22

USB Power 22

Connecting to an Additional SNAP Device 22

Using usb_modeswitch 23

Factory Restore / Re-Flashing Your E12 24

Restoring from a MicroSD Card 24

Specifications and Installation 25

Specifications 25

E12 Dimensions 26

Troubleshooting Common Problems 27

The Ethernet port does not work or eth0 does not appear in ifconfig 27

SNAPconnect is not working 27

I cannot SSH into my E12 27

Regulatory Information and Certifications 28

Overview

IoT solutions demand reliable and flexible wireless connectivity at scale. SNAPconnect gateways are the interface

between your SNAP mesh networks and the rest of the world. Whether performing data aggregation to quickly

make real-time decisions, merging multiple IoT data streams, or connecting to on-site servers or the cloud,

SNAPconnect gateways provide the connectivity your network needs

915MHz and 2.4GHz Flexibility

IoTapplications exist in many environments. That's why the SNAPconnect E12 Gateway is available in 915MHz and

2.4GHz versions. Both versions are powered by SNAP: the Things Platform, so you can switch between frequencies

without having to redesign your application. It's even possible to have SNAPnetworks of both frequencies in the

same environment, sending information to the same cloud repository.

Powered by Ubuntu - Easy to Customize

The SNAPconnect E12 Gateway is an embedded Ubuntu Linux computer with the flexibility to add custom or 3rd

party software as needed for local databases, IoT platform clients, or other elements. It bridges SNAP edge

networks over Ethernet or optional USB connectivity devices such as cell modems, Bluetooth, or Wi-Fi adapters.

Start Quickly with Included Tools

The E12 is ready-made to host SNAP Thing Services – a suite of software tools that unite IoT devices and

applications via REST and MQTT for tasks such as data collection, device updates, and network management.

Custom programs can be created with the help of SNAPconnect software libraries making communications with IoT

devices in edge networks easy, even in challenging environments.

Protect your Deployment

SNAPconnect gateways emphasize security using AES-128 to encrypt edge network traffic, and standard Linux

security tools to secure the backhaul network. SNAP Thing Services utilizes tools like TLS and HTTPS to secure

outbound interfaces.

1

The Device

The images below show an E12 gateway with all features marked:

All E12s include a SNAP-powered module, and will come with an antenna for the module's connection labeled with

the Synapse S on the E12's case.

2

SNAPconnect E12 User Guide — 116-081614-030-B001

Getting Started

Adding an E12 gateway to your SNAP network is easy, but as with adding any computer to any network, if you don’t

follow the right steps, you’ll end up in the wrong place. These directions provide the steps for connecting to your E12

from either a Windows PC or a Linux PC, which we will refer to as your host PC. These instructions assume that you

have some familiarity with your host operating system. See your OS help files if you need assistance installing

software or navigating applications.

To get started with the E12, you'll first need to apply power.

Powering the E12

The E12 is powered through the power terminal

blocks.

Use only UL 60950-1 2nd Edition AM1+AM2

certified LPS power supplies, rated for relative

environmental conditions suitable to your use

location with an output of 7-36VDC, 1500mA Max.

NOTE: Some power supply vendors mark the positive “+” lead with a white stripe.

NOTE: The E12 cannot be powered over the USB SERIAL port.

NOTE: If the E12 is installed into an end product, wiring should be done in accordance with the relevant product

safety standard of the end product.

Establishing a Serial Connection

Next you'll need to establish a USBserial connection.

To establish a serial connection to the E12 and update the software:

1. Ensure that you have terminal emulation software installed on your host PC. Popular software for this purpose

includes Tera Term, PuTTY, minicom, screen, or any of many others.

2. Use a standard USB to micro-USB cable to connect the micro-USB port on your E12 to an open USB port on

your host PC .

3. Apply power to the E12.

3

NOTE: During the upcoming step 4, if you find that your host PC cannot connect to the E12 over the USB

connection, you may need to install the FTDIUSBto UART VCP drivers, available from http://www.ftdichip.com

4

SNAPconnect E12 User Guide — 116-081614-030-B001

4. Find the serial port that your host PC has assigned to the E12 (over that USB connection)

To find the serial port on a Windows PC:

a. Check under “Ports” in the Device Manager.

b. Look for USBSerial Port (COMxx) where the xx will indicate the serial port assigned (e.g., COM3, or

COM88).

c. Connect using your preferred terminal application. Example screenshots of connecting via PuTTY and

TeraTerm are provided below:

To find the serial port on a Linux PC:

a. Before plugging in the E12’s USB cable, check for ttyUSB connections in the /dev directory.

5

b. Plug in the E12 and look for a new ttyUSBx, where x indicates the USB connection assigned (e.g., ttyUSB0).

If you had any other USB-serial devices plugged in, you may see more than just /dev/ttyUSB0, which is

why you should check for the presence of these devices first.

c. You can use any of a number of serial terminal programs to connect to your serial port. Linux versions of

PuTTy and TeraTerm exist and work the same way shown in the Windows examples above (other than

the name of the port to which you are connecting. additionally, utilities such as cu or screen are available

as well:

Using cu:

To connect: sudo cu –l /dev/ttyUSB0 –s 115200

To disconnect, at the command line type ~. (tilde, period) and then press Enter.

Using screen:

To connect: sudo screen /dev/ttyUSB0 115200

To disconnect, press Ctrl-A, and then \ (backslash).

5. Using your terminal emulator, connect to the E12 using the following serial port settings:

l 115200 baud

l 8 bits

l No parity

l 1 stop bit

l No flow control

6. Use your terminal emulation window to log in to the E12 gateway.

Username: snap

Password: synapse

NOTE: You must change your password the first time you log in. This prevents you from installing an E12

gateway with the default password set, which is pretty much the definition of a bad security idea. Ubuntu

enforces some restrictions on what constitutes a valid password, and these instructions are further defined

in the Ubuntu documentation available at https://help.ubuntu.com/.

7. Connect your E12 to the internet.

The easiest way to do this is to make a wired connection to a host (i.e., router) that supports DHCP. (Most do,

by default.) If you wish to configure your device for a static IP address, you may do so via the serial connection

before making your internet connection.

8. Update the Python Development Libraries

Before starting work with the E12, you'll want to make sure you have the latest versions of the software

installed on the unit. The E12 makes use of Python Development Libraries that are sometimes updated to add

6

SNAPconnect E12 User Guide — 116-081614-030-B001

new functionality and correct bugs. You can update the version installed on your unit by running the

command:

sudo apt-get install python-dev

NOTE: Remember that Ubuntu Linux does not, by default, enable root as a user. The sudo command

temporarily escalates your privileges to su (super user), so the E12 will prompt you for your password.

NOTE: If you get a "Requirement already satisfied" message from one of the updates, don't be alarmed. It

just means you already have the latest version.

9. Set the Clock

First, you should specify the timezone in which your device will reside. An easy way to do this is to use tzdata,

which allows you to select the general region, and then select the specific zone for your location. You can run it

with the command:

Sudo dpkg-reconfigure tzdata

Next, and only if the E12’s date is not set (i.e. it is not connected to a network so it does not set the date from an

NTP server, and the hardware clock has never been set), set the date manually.

The following example sets the date to April 20, 2016, at 12:30:59 p.m.

sudo date --set “2016-04-30 12:30:59”

Sat Apr 30 12:30:59 CDT 2016

You can set the hardware clock from the system clock using the hwclock command.

sudo hwclock -wu

10. Update SNAPconnect

The SNAPconnect software enables the connection from your E12 device to the rest of your SNAP-powered

network.

To update SNAPconnect, type the command:

sudo –H pip install --upgrade snapconnect –i https://update.

synapse-wireless.com/pypi/

11. Update PyCrypto

The PyCrypto project is required for using AES128 encryption on your radio network.

To update PyCrypto type the command:

sudo -H pip install --upgrade pycrypto

That's it! Your E12 is now ready to work with your SNAP-powered network. Your Python program, using the

SNAPconnect library or the SNAPtoolbelt utilities, interfaces with the gateway's SNAP module directly, and the rest

of your nodes through that. You can also have full internet access via the wired Ethernet connection.

Now it’s up to you to do awesome things with your SNAP-powered network.

You can find examples of other people’s efforts on the Synapse Wireless repository at GitHub:

https://github.com/synapse-wireless.

7

The site includes sample projects for things like sending data collected by SNAP-powered nodes to cloud services,

or an E12-hosted web server. Download the code there, or fork it for your own projects. Better yet, contribute to the

code base for other users.

Mounting the E12

The E12 has mounting holes on the outside flanges of the unit, any of which can be used for mounting the E12 to a

solid surface.

8

SNAPconnect E12 User Guide — 116-081614-030-B001

E12 Software Specifics

The E12 uses Canonical’s Ubuntu 14.04, running a custom Linux kernel based on the Beaglebone Black kernal.

There are many resources out there for learning about Ubuntu online, and the topic possibilities far exceed the

scope of this manual. However there are a few details that warrant discussion.

Passwords and root Access

The default configuration for Ubuntu Linux is to have the root user disabled. This is a security precaution, as it means

a hacker who comes across a connection to your device does not automatically know the login name of a user with

full administrative rights to your device.

Instead, Ubuntu works with the sudo paradigm; when you need to perform a function that requires administrative

access, you preface your command with sudo and are prompted for your password (as a reminder that what you

are doing could potentially affect the device’s ability to function).

The default snap user on the E12 has sudo access, and can perform all device administrative tasks. You can create

user accounts on the device and grant them sudo access as well. For added security, you can create sudo-enabled

user accounts and then delete the snap user account to further reduce a potential hacker’s knowledge of how to

access the gateway.

If you would rather work with the root account anyway, you can enable it by assigning a password:

sudo passwd root

Similarly, you can change the snap password with the same command:

sudo passwd snap

NOTE: No account can connect via SSH without a password, though connecting over a serial terminal session is

possible for accounts with no password.

E12-Specific Software Packages

The E12 comes with several support packages installed, and additional ones are available via apt and pip.

NOTE: Before installing new packages, be sure to run sudo apt-get update to sync your E12 with the

package servers and obtain the newest version. This action may take a few minutes, depending on your internet

connection speed.

You can pull the latest updates for your gateway by calling:

sudo apt-get update

sudo apt-get install gateway-updates-latest

9

You can also forego the previous commands and install updates individually. Note that the steps below

achieve the same outcome as the sudo apt-get update and sudo apt-get install

gateway-updates-latest commands.

First, you can upgrade SNAPconnect and the encryption libraries necessary for AES128 communications

using these commands:

sudo –H pip install snapconnect –i https://update.synapse-

wireless.com/pypi/

sudo -H pip install --extra-index-url https://update.synapse-

wireless.com/pypi snaptoolbelt

sudo -H pip install pycrypto

Finally, check for any updates to other E12-specific packages1:

sudo apt-get install E12-leds E12-buttons E12-gpio-scripts E12-network-

help E12-snap-utils

These installations include the following packages, which are installed in /usr/local/bin except where noted

otherwise:

E12-leds, E12-buttons packages – a simple LED
and button control scripts package

E12-gpio-scripts package - Initializes GPIO lines
(/etc/rc2.d)

E12-snap-utils package – maintenance and
support scripts for RF220SU.

led-1, led-2, led-

Controls lighting for leds

3, led-4, led-a

button Reads button states

Startup script to initialize

S30gpios

GPIO lines package

reset-snap-node resets the RF220SU

wakes the RF220SU (if it

wake-snap-node

was sleeping)

performs maintenance on

flash-bridge

the RF220SU

1

Remember that copying and pasting from PDF files can give unpredictable results. Try pasting into a text editor first

to be sure that the complete command comes across as one line, and that there are not added characters in your

pasted text. Then, copy from the text editor and paste into your command window. Or, type it into the command

window directly.

10

SNAPconnect E12 User Guide — 116-081614-030-B001

E12 Physical Interfaces

The E12 includes a tri-color LED that you can control from your programs, plus a button you can monitor. Control

scripts in the E12-led and E12-button packages assist with controlling the LED and monitoring the button.

E12 LEDs

The four processor-controlled LEDs are single color - green - and by

default are activity indicators. The LEDs are numbered 1 - 4 proceeding

from left to right. You can set the LED state using the following commands:

l led-1 on / led-1 off

l led-2 on / led-2 off

l led-3 on / led-3 off

l led-4 on / led-4 off

l led-a [red | green | amber | off]

led1 is closest to the terminal blocks and is labeled "1".

An additional LED is on the side of the E12 next to the antenna. This LED, known as LEDA, is

controlled via the Linux instance running on the E12. The other LED, LEDB, is controlled via

the SNAPpy script running on the internal SM220 module.

Finally, there are two LEDs on the E12 ethernet port. A green LEDthat indicates the E12 is

connected to the network, and a yellow LEDthat illuminates when the E12 is configured for

100Mbps communications.

The SNAPModule-Controlled LED

The unit's SNAPmodule controls the tri-color LED on the antenna side of the case (LEDA) via GPIO_1 (green) and

GPIO_0 (red). (For amber, use both green and red.) This LED is only accessible via the SNAPmodule. It cannot be

controlled by the E12’s AM335x processor, except through calls to the SNAPmodule.

These two IO lines from the SNAPmodule will light their respective colors when written high. This sample code

demonstrates its use:

from synapse.platforms import *

GREEN=GPIO_1

RED=GPIO_0

@setHook(HOOK_STARTUP)

def onStartup():

setPinDir(RED, True)

11

setPinDir(GREEN, True)

LED_off()

def LED_off():

writePin(RED, False)

writePin(GREEN, False)

def LED_green():

writePin(GREEN, True)

writePin(RED, False)

def LED_red():

writePin(GREEN, False)

writePin(RED, True)

def LED_amber():

writePin(RED, True)

writePin(GREEN, True)

LEDA is the only LED controllable directly from the SNAPmodule. The other three LEDs are controlled from the E12’s

AM335x processor.

The E12 Button

The button on the bottom of the E12 is fully user-accessible. You can monitor the button state at GPIO 112. The E12-

buttons package provides a Bash script that prints the button status to STDIO and returns the button status (as 1 for

up or 0 for pressed).

You can monitor the AM335x processor GPIO directly rather than using the Bash script if you find that to be easier.

Unlike the Bash script that set states on the E12, this script does not require sudo access to run.

12

SNAPconnect E12 User Guide — 116-081614-030-B001

Working With the Gateway's SNAPModule

The E12 supports an internal SNAPmodule for 915MHz or 2.4GHz

communications depending on the unit you purchased. These modules are

interchangable, and the E12 can access the SNAPmodule serially via serial ports

/dev/snap0 and /dev/snap1 connecting to UART0 and UART1 on the

module, respectively. By default, SNAP-powered modules communicate serially

over UART1, so when making your SNAPconnect or SNAPtoolbelt connection to

the module, you should use /dev/snap1 unless you have modified your

modules’s default UART settings.

For detailed instructions on SNAPconnect, please consult the SNAPconnect

Python Package Manual, available from http://developer.synapse-

wireless.com/software/snapconnect.

In addition to the serial connections, there is one GPIO pin from the E12 that is tied to the module for controlling and

signaling.

l GPIO 48: Tied to the Reset pin on the RF220SU, you can use this pin to reboot the module.

Waking the SNAPModule

At times it may be helpful to have the SNAPmodule in your E12 sleep, and then be woken by the E12’s processor. If

you have installed the recommended E12-snap-utils package, you can easily do this by defining GPIO_F1 on the

SNAP module as a wake pin, like this:

from synapse.pinWakeup import *

from synapse.platforms import *

@setHook(HOOK_STARTUP)

def onStartup():

setPinDir(GPIO_12, False)

setPinPullup(GPIO_12, True)

wakeupOn(GPIO_12, True, True)

Now, whether your SNAP module is in a timed sleep or an untimed sleep, having the code on your E12 invoke this

command will wake the SNAP module:

/usr/local/bin/wake-snap-node

This command invokes a Bash script to pull the E12s GPIO33 high, pause a second, and then pull the line low. The

Bash script must be invoked as sudo or by a process invoked as sudo. You can examine the Bash script to see

how the GPIO value is controlled for use in your own scripts, should you wish to use the pin as a one-bit signal to the

SNAP module.

13

Resetting the SNAPModule

There is a pin you can use to reset your module should you need to. (This is necessary, for example, when you reset

factory parameters on the node.)

The E12-snap-utils package also provides a script to assist with this. Invoke this Bash script to briefly pull the reset pin

low and then release it to high, resetting the node:

/usr/local/bin/reset-snap-node

While it is important to be able to do this, in most circumstances it will be less useful day-to-day. (If you need to reset

your SNAPmodule daily, you may have code issues you need to address.)

Restoring Functionality to an Unresponsive SNAPModule

The risk of having a module that provides several configuration options is it expands the possibility of a

misconfiguration causing you to lose contact with the module. Several things can make a module unresponsive,

from setting an encryption key that you then forget, to putting a script on the device that sends the node to sleep with

an invalid wake pin defined.

The Synapse Wireless Portal software provides mechanisms for node recovery, but since you cannot make a serial

connection from the SNAPmodule in your E12 to Portal, that functionality needs to exist on the E12 as well.

If you find that your SNAP module is unresponsive or unreachable over the air or serially, the first suspect is typically

the user script on the module. Many a programmer has accidentally specified the wrong wake pin or accidentally

dropped a node into an endless loop. So, the first thing to try in module recovery is forcibly removing the SNAPpy

script from your SNAPmodule:

sudo flash-bridge -e -p RF220 (for 2.4GHz equipped gateways)

sudo flash-bridge -e -p RF320 (for 915MHz equipped gateways)

WARNING: Addressing the wrong firmware for your unit may render it inoperable, perhaps even permanently. If

you are unsure of which firmware to address, contact Synapse customer support.

This leaves your SNAP module’s NV parameters untouched, but removes the existing SNAPpy script from the node.

You can then load an appropriate script over the air or serially.

If this does not restore your access to the node, the most likely reason for your inability to communicate is

mismatched configuration (NV) parameters on the node. This could be the result of different encryption keys or

encryption types, misconfigured UARTs, differences in how many CRCs are expected, or some other configuration

setting. The easiest thing to do next is to have the node default its NV parameters, which you can also do with

flash-bridge:

sudo flash-bridge -nv -p RF220 (for 2.4GHz equipped gateways)

sudo flash-bridge -nv -p RF320 (for 915MHz equipped gateways)

14

SNAPconnect E12 User Guide — 116-081614-030-B001

This clears the encryption settings (no key, no encryption), sets UART connections to their default settings (UART1,

38,400 baud, 8N1), and clears other settings to their default levels. (Refer to the SNAP Reference Manual for what

the defaults are for your firmware version.)

Typically it is best to start with clearing the script in your node before resetting its parameters, because it is possible

for the script to reset (away from default values) parameters that you just reset (to default values).

NOTE: Resetting your SNAP module to default settings does not automatically mean that other devices can talk

to it, over the air or serially. It does mean that you now know how to configure those devices to talk to it.

If you have another radio device on channel 13 using network ID 0xABCD, you will have to set that device to

channel 4, network ID 0x1C2C to talk to your defaulted SNAP module. You can then use that radio connection to

move the E12’s SNAP module to your preferred network settings. Or, you could change those settings serially

from your E12 — if your E12 is set to communicate serially the way that your SNAP module is (considering

encryption keys and types, serial rates, etc.).

The point is: defaulting a device doesn’t mean you have it where you want it, only that you now know where to

go look for it.

Upgrading the SNAP Module Firmware

Synapse Wireless is always working to improve the experience with SNAP-powered networks, and that means new

firmware every now and then. If you find that you want to upgrade the firmware in your gateway's SNAP module, you

can do it over the air or serially from the E12. You'll need to download the firmware appropriate to your SNAPmodule

by typing:

sudo -H pip install snap_firmware_2.8.1 -i https://update.synapse-

wireless.com/pypi/

The flash-bridge command we’ve been using for clearing scripts and resetting parameters saves the day again:

sudo flash-bridge –i <imageName> -p RF220 (for 2.4GHz gateways)

sudo flash-bridge –i <imageName> -p RF320 (for 915MHz gateways)

For this command, <imageName> refers to an absolute or relative path to a Synapse firmware image file, which will

have the extension .sfi.

Loading new firmware erases the script previously in the node but does not change any NV parameters (unless the

two firmware versions, old and new, have different default values for something).

15

For example:

First, download SNAPfirmware version 2.8.1 by typing:

sudo -H pip install snap_firmware_2.8.1 -i https://update.synapse-

wireless.com/pypi/

This will download the firmware images and put them in the folder:

/usr/local/lib/python2.7/dist-packages/snap_firmware_2_8_1/

Then you can update the E12 by typing:

For 2.4GHz Gateways:

sudo flash-bridge -i /usr/local/lib/python2.7/dist-packages/snap_firmware_

2_8_1/RF220SU_AES128_SnapV2.8.1.sfi

For 915MHz Gateways:

sudo flash-bridge -i /usr/local/lib/python2.7/dist-packages/snap_firmware_

2_8_1/RF320SU_AES128_SnapV2.8.1.sfi

16

SNAPconnect E12 User Guide — 116-081614-030-B001

Accessing the MicroSD Slot

The E12 includes an on the board2microSD slot for reflashing your device to its factory state. You can also use a

card in this slot as additional flash storage on your gateway if you need it.

The following instructions will work for ext4-, FAT32-, or exFAT-formatted cards. Ubuntu Linux 14.04 does not

support exFAT by default. You will need to run the following command for exFAT support:

sudo apt-get install exfat-fuse exfat-utils

To access a card in the microSD slot:

1. Insert the microSD card into the microSD card slot at the end of the E12:

2. Create a mount point for the card. In this example, the directory will be named sdcard, and it will be in the /mnt

directory. (If you have previously done this, you do not need to repeat it.)

sudo mkdir /mnt/sdcard

3. Mount the card. (For these commands, replace p1 with the partition number you want to mount.)

a. For cards formatted with the ext4 file system:

sudo mount –t ext4 /dev/mmcblk0p1 /mnt/sdcard

b. For cards formatted with the FAT32 file system:

sudo mount –t vfat /dev/mmcblk0p1 /mnt/sdcard

c. For cards formatted with the exFAT file system:

sudo mount –t exfat /dev/mmcblk0p1 /mnt/sdcard

You can confirm it is mounted by using the mount command and looking for an entry like the following (with the

appropriate file system format):

/dev/mmcblk0 on /mnt/sdcard type ext4 (rw)

You can use the ls command to list the available partitions:

ls /dev/mmcblk0p*

2

Early versions of the hardware may not include this feature. See the Factory Restore / Re-Flashing Your E12 on

page 24. section later in this document to determine whether your hardware has it.

17

Common Linux Operations

The E12 uses Ubuntu 14.04 as its operating system, so you will need to have some Linux knowledge to use the

gateway. The internet provides ample documentation for all operations within the capability of the E12, and “Linux

Manual” is beyond the scope of this document.

However there are a few operations that are likely to be popular, based on the nature of a gateway. The following

information may save you some time (and frustration) from searching the internet.

Editing Linux Files

Many of the configuration suggestions below instruct you to create new files on your E12 or edit existing files. There

are several ways to go about this, depending on your choice of methods and tools.

The method that old-school Linux gurus might mock you for not using is the classic Vim (Vi IMproved) text editor. If

you are already comfortable in vi or Vim, kindly skip to the next section.

For people who prefer a little more help on screen, the popular nano text editor is included in the basic E12

distribution. You can edit a file directly by typing nano /path/to/filename, or open nano and then open the file

directly from within the editor. Remember that if you are attempting to edit a file that your user does not own (e.g.,

files in /etc that are owned by root) you should preface your nano command with the sudo command in order to

open the editor with escalated privileges.

3

The third option for creating or editing files for the E12 is to create the files on another system completely and then

move them into place on the E12. You can move them over an SSH connection or by “sneaker net” using a USB

drive. This is the most cumbersome editing option for files changes, but for more elaborate software suites it may be

appropriate to install your package this way. If you use this method, remember that Windows and Linux use different

line endings. You may need to update your file’s line endings to the Linux standard using a command like this:

sed -i -e 's/\r//' file

Making Your Software Run at Startup

There are two main types of things you might want to invoke at startup:

l Scripts that run to completion, such as configuration or logging scripts.

l Applications that you want to start as a service that can be started, stopped, and restarted.

As with many things in the Linux world, both of these are easy once you know how.

Running a Script to Completion

Like many Linux distributions, Ubuntu does not follow all the standards. One such place is that by default, Ubuntu

boots to runlevel 2, which allows for multiuser connectivity (per the standards) and networking (which the standards

3

Emacs is not included in the base Linux distribution on the E12. You can get it using sudo apt-get install emacs

18

SNAPconnect E12 User Guide — 116-081614-030-B001

provide at runlevel 3). This is important because it affects where you should add your run-once scripts to have them

execute.

There is a Bash script located at /etc/rc.local that executes every time the runlevel changes to a new

multiuser level. In normal operation, the E12 boots to runlevel 2 and stays there. If you are not actively initializing a

new runlevel, this script will only run on boot. You can add commands to this Bash script, which by default does

nothing.

As an alternative, you can add a Bash script in the /etc/rc2.d/ directory to have the script execute each time

runlevel 2 is initialized. (This script would run before the rc.local script executes.) This /etc/rc2.d/ directory

contains a README file that provides some instructions for naming and configuring your script to run on boot.

Starting a Service

For applications you want to have started as a service, which can be started, stopped, and restarted, you can create

an upstart service at /etc/init/.

As an example of making a SNAPconnect application run as a service, create a file named

/etc/init/MyOwnApp.conf and put the following text in it:

# SNAPconnect - start a SNAPconnect application as a service

#

description "Start SNAPconnect"

start on runlevel [2]

stop on runlevel [!2]

exec python /home/snap/my_snapconnect_example.py

The command python /home/snap/my_snapconnect_example.py would then be executed on boot and

stopped on shutdown (or on transition to any other runlevel).

If you want your application to automatically restart (such as if it crashes) you can add the respawn option:

# SNAPconnect - start a SNAPconnect application as a service

#

description "Start SNAPconnect"

start on runlevel [2]

stop on runlevel [!2]

respawn

exec python /home/snap/my_snapconnect_example.py

You could also administer the application with these commands:

sudo service MyOwnApp start

sudo service MyOwnApp restart

19

sudo service MyOwnApp stop

This basic example gives you a starting point for starting your own services. Examine the other *.conf files in the

/etc/init/ directory for further examples of how to configure your services.

Setting Your E12’s Clock

The E12 has an NTP client that connects to time servers on the internet to keep its clock set appropriately (to UTC).

However the system clock and the hardware clock can get out of sync over time, resulting in the E12 using the

hardware clock’s time when internet connectivity isn’t available.

NOTE: These steps are typically performed during setup. The information is repeated here for ease of

reference.

First, you should specify the timezone where your device will reside. An easy way to do this is to use tzdata, which

allows you to select the general region, and then select the specific zone for your location.

sudo dpkg-reconfigure tzdata

Next, and only if the E12’s date is not set (i.e. it is not connected to a network so it does not set the date from an NTP

server, and the hardware clock has never been set), set the date manually. The following example sets the date to

April 20, 2016, at 12:30:59 p.m.

sudo date --set “2016-04-30 12:30:59”

Sat Apr 30 12:30:59 CDT 2016

You can set the hardware clock from the system clock using the hwclock command.

sudo hwclock -wu

Resetting a Lost User Password

If there’s one thing you can count on, it’s that at some point a user will forget his or her password. If you have another

administrative (sudo) user defined on the device, that user can reset the lost password.

However, if you have forgotten all the passwords for every account, the only way to regain control of your gateway is

to reflash your gateway.

As a preventative measure, you can use the built-in recovery utility to create a flash drive key which will unlock a

single user account on your gateway if the flash drive is present on bootup. The key will be unique and for one time

use, meaning after you reset a password with it, that key won't work again (the flash drive will still be a normal flash

drive.)

To make a recovery flash drive, first ensure you have the newest version of the utility:

sudo apt-get install 50-password-reset

Then, insert the flash drive you wish to store your recovery key, and run:

sudo generate-usb-password-reset USERNAME

20

SNAPconnect E12 User Guide — 116-081614-030-B001

Where username is the account you wish to be unlocked if this flash drive is present on boot. The key will then be

written to the flash drive and stored locally on your gateway. On subsequent boots, if the flash drive containing the

key is present, the account specified will have it's password deleted, and you will have to supply a new password

upon logging in. The key will NOT work again after use.

If you need to create recovery keys for multiple gateways, you can use the same flash drive multiple times. A unique

key will be generated per gateway, but they can all be stored on the same flash drive and the only one which will be

removed is the one which was used.

Mounting an External Drive

The USB connection on the E12 is available for mounting external storage, whether that's a flash drive for “sneaker-

netting” files, or a larger drive for data aggregation. You can mount and unmount the external drive using these

commands, changing the number from 1 to the number appropriate for the partition on your drive:

sudo mount /dev/sda1 /mnt

sudo umount /dev/sda1

These will mount (and then unmount) the external drive to the /mnt directory in your E12’s file system. You can

specify the mount point of your choice, but the mount point must exist as a directory before the drive can be mounted

to it.

21

Extending the E12 with USB Accessories

The E12 has drivers to support many USB devices, such as a second SNAP-powered bridge (using an SN220 or

SN132 carrier board), Wi-Fi devices, cell modems, or external storage. While the complete details of configuration

options available on these devices fall outside the scope of this document, there are some common considerations

that may prove useful.

USB Power

The USB 2.0 connection on the E12 is not rated as a “battery-charging” connection, and may not provide sufficient

current for high-drain devices, such as some external hard drives.

If you find you are having problems with your USB devices (e.g., external hard drives failing to mount, or cellular

connections losing their connections), we recommend you try connecting the device to the E12 through a powered

USB hub.

Connecting to an Additional SNAP Device

The E12 can support a second SNAP-powered node through its USB port. You can connect an SN132 or SN220

SNAPstick, or you can use an FTDI USB-serial cable to connect to an SN171 ProtoBoard or some other hardware that

uses a DE9 connector to make an RS232 serial connection.

This can allow your E12 to act as a bridge between two radio subnets, where radios are on some combination of

different frequencies, different network IDs, and/or different channels.

The E12 provides the drivers that support the FTDI USB-serial cable and the SN132 inherently. To use the SNAPstick

SN220, you need to modify it to operate as a serial device rather than a USB device. For instructions on doing this,

refer to the Synapse Wireless technical brief “Configuring an SN220 SNAPstick as a COM Port,” available on the

Synapse developer microsite at http://developer.synapsewireless.com/.

Whichever device you use, plug the device into the E12’s host USB port and (among other messages) you should see

something similar to:

usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0

or:

usb 1-1: cp210x converter now attached to ttyUSB0

The key here is the line that says “converter now attached to ttyUSB#” (ttyUSB0, in the example shown). You will use

this device handle, “ttyUSB#”, to communicate with the SNAP device. In your SNAPconnect application, you would

open a connection to the device like this:

com.open_serial(type=SERIAL_TYPE_RS232, '/dev/ttyUSB0')

22

SNAPconnect E12 User Guide — 116-081614-030-B001

Using usb_modeswitch

Many USB Wi-Fi and cell modems now come with a small amount of onboard storage, typically used to automatically

install drivers when connected to a Windows host. When the device first connects, it appears as a small flash drive or

virtual CD-ROM. After installing the necessary drivers, the Windows host sends a signal to the device instructing it to

“mode switch” – to unmount the storage and expose itself as a Wi-Fi (or cellular) device.

Ubuntu Linux also automatically handles many of these devices. But there may be some out there that Ubuntu does

not recognize by default. If you find that the E12 is not recognizing your device, consider installing usb_

modeswitch, which contains a library of parameters for converting devices like these.

sudo apt-get install usb-modeswitch

Then, plug your device in again and you are likely to find that it works as expected.

23

Factory Restore / Re-Flashing Your E12

From time to time you may need to restore an E12 to the factory default state. The instructions below will help you do

that.

Restoring from a MicroSD Card

l Download the newest microSD card E12 installer image from:

https://developer.synapse-wireless.com/downloads/gateways/index.html#gateway-downloads

l Write this image to your microSD card.

l In Windows, this is easiest using something like Win32DiskImager.

l In Linux, you can use dd from the command line, :

$dd if=E12-VERSION-sdcard.img of=/dev/sdX bs=1M

# where E12-VERSION-sdcard.img is the sdcard image file

# and /dev/sdX is the device file of the uSD card device

$sync

$eject /dev/sdX

WARNING: Make sure that the “of” variable points to the correct device before executing this command. (An

easy way to verify which device is the SD card is to execute the ls command in the /dev directory before and

after inserting the SD card.) Writing to the wrong device could potentially overwrite critical information such as

your system hard drive.

l Remove power to the device.

l Insert the microSD card into the microSD card slot.

l Hold the button near the USBport, apply power, and release the button. On older boards, you may

experience a 4 - 5 minute delay before the board begins programming. You can identify affected boards by a

black Synapse logo next to the programming button.

l A few moments after programming begins, LEDs 1, 2, 3 and 4 will begin cycling to indicate the E12 is being

programmed.

l After about five minutes (your time may vary depending on factors such as the speed of your microSD card),

the LEDs will all blink and then stay on, indicating that the process is complete.

l Disconnect power from the device, and remove the microSD card.

l Your E12 is now refreshed and ready to use.

24

SNAPconnect E12 User Guide — 116-081614-030-B001

Specifications and Installation

The Synapse Wireless E12 gateway is a free-standing ARM Cortex-A8 based Linux computer running Ubuntu 14.04,

and incorporating a 915MHz or 2.4 GHz Synapse RF module that connects the device to SNAP-powered mesh

networks. The gateway is available with serial connectivity through a microUSB connection, and Ethernet

connectivity through the RJ-45 connector.

This arrangement provides for a wide range of possibilities for monitoring sensor networks, controlling remote

devices, and driving the internet of things.

Specifications

E12

OS Ubuntu 14.04 LTS, Linux kernel

CPU TIAM335x 1GHz

Flash 4GB NAND FLASH memory

RAM 512M DDR3

10/100 Ethernet

Ports

Operating Temperature -40C - 70C*

Board Size 15.5cm x 9cm x 2cm

Unit weight 582 grams (without antennas)

Input Voltage

Storage Expansion µSD – internal

LEDs / Buttons

uSDcard

USB 2.0 Type-A

USB Micro-B (serial)

Nominal: 12-24V DC

Absolute: 7-36V DC

4 Green LEDs

2 Red/Green LEDs

1 Button

NOTE: This equipment is certified by Underwriters Laboratories for operation in a maximum ambient

temperature of 60°C. The product safety standard to which this unit is evaluated and certified, IEC 60950-1, and

UL 60950-1 for the US and Canada, specifies a maximum temperature limit of 70°C on metal surfaces that may

be touched. During operation, there is a slight temperature rise on the surfaces of the E12. Therefore, when

installed into an ambient environment at 70°C, the surface temperatures on the E12 may exceed the limit of

70°C.

25

E12 Dimensions

26

SNAPconnect E12 User Guide — 116-081614-030-B001

Troubleshooting Common Problems

The Ethernet port does not work or eth0 does not appear in ifconfig

Most likely, your MAC address has not been set. If you run ifconfig -a and see output similar to:

eth_badmac Link encap:Ethernet HWaddr 00:1c:2c:ff:ff:ff

Your MAC address has reverted to the default and needs to be set. See SNAPconnect is not working below.

SNAPconnect is not working

Check for one of the following possible issues:

l SNAPconnect may be out of date – prior versions of SNAPconnect were incompatible with some version of

the Python Tornado package or may have failed to obtain the MAC address correctly. Upgrade to the latest

version of SNAPconnect by using the instructions in E12-Specific Software Packages.

l Your MAC address is not set:

From the linux command line, run:

sudo fw_setenv ethaddr "00:1c:2c:xx:xx:xx"

(Replace the XX entries with your last three octets of your Ethernet MAC address, which should be found on

the label on your E12’s case. Be sure to use the Ethernet MAC address (labeled ETH MAC) and not the SNAP

MAC address.)

Then reboot.

I cannot SSH into my E12

You cannot SSH into the E12 as root, or any user account which does not have the password set. Be sure to have set

a password for the account you want to use to connect.

27

Regulatory Information and Certifications

RF Exposure Statement

This equipment complies with FCC radiation exposure limits set forth for an uncontrolled environment. This

equipment should be installed and operated with minimum distance of 20cm between the radiator and your body.

This transmitter must not be co-located or operating in conjunction with any other antenna or transmitter.

FCC Certifications and Regulatory Information (USA Only)

FCC Part 15 Class B

These devices comply with part 15 of the FCC rules. Operation is subject to the following two conditions: (1) These

devices may not cause harmful interference, and (2) These devices must accept any interference received, including

interference that may cause harmful operation.

Radio Frequency Interference (RFI) (FCC 15.105)

This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to Part 15 of

the FCC rules. These limits are designed to provide reasonable protection against harmful interference in a

residential installation. This equipment generates, uses and can radiate radio frequency energy and, if not installed

and used in accordance with the instructions, may cause harmful interference to radio communications. However,

there is no guarantee that the interference will not occur in a particular installation. If this equipment does cause

harmful interference to radio or television reception, which can be determined by turning the equipment off and on,

the user is encouraged to try to correct the interference by one or more of the following measures: Reorient or

relocate the receiving antenna. Increase the separation between the equipment and receiver. Connect the

equipment into an outlet on a circuit different from that of the receiver. Consult the dealer or an experienced radio/TV

technician for help.

If this equipment does cause harmful interference to radio or television reception, which can be determined by

turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the

following measures:

l Reorient or relocate the receiving antenna.

l Increase the separation between the equipment and receiver.

l Connect the equipment into an outlet on a circuit different from that to which the receiver is connected.

l Consult the dealer or an experienced radio/TV technician for help.

Labeling Requirements (FCC 15.19)

This device complies with Part 15 of FCC rules. Operation is subject to the following two conditions: (1) this device

may not cause harmful interference, and (2) this device must accept any interference received, including

interference that may cause undesired operation.

28

SNAPconnect E12 User Guide — 116-081614-030-B001

If the FCC ID for the module inside this product enclosure is not visible when installed inside another device, then the

outside of the device into which this product is installed must also display a label referring to the enclosed module

FCC ID.

Modifications (FCC 15.21)

Changes or modifications to this equipment not expressly approved by Synapse Wireless, Inc. may void the user's

authority to operate this equipment.

Declaration of Conformity

(In accordance with FCC 96-208 and 95-19)

Manufacturer's Name: Synapse Wireless, Inc.

Headquarters: 6723 Odyssey Drive, Huntsville, AL 35806

Synapse Wireless, Inc. declares that the product:

Product Name:E12-0

to which this declaration relates, meet the requirements specified by the Federal Communications Commission as

detailed in the following specifications:

l Part 15, Subpart B, for Class B equipment

l FCC 96-208 as it applies to Class B personal computers and peripherals

The products listed above have been tested at an External Test Laboratory certified per FCC rules and has been

found to meet the FCC, Part 15, Emission Limits. Documentation is on file and available from Synapse Wireless, Inc.

Industry Canada (IC) Statement

This Class B digital apparatus complies with Canadian ICES-003.

Cet appareil numérique de la classe B est conforme à la norme NMB-003 du Canada.

29