TS-7553-V2: Difference between revisions

From embeddedTS Manuals
(→‎eMMC Interface: Fixed typos)
Line 525: Line 525:
The i.MX6UL SD card controller supports the MMC specification, the TS-7553-V2 includes a soldered down eMMC IC to provide on-board flash media.     
The i.MX6UL SD card controller supports the MMC specification, the TS-7553-V2 includes a soldered down eMMC IC to provide on-board flash media.     


Our default software image contains 2 partitions:
Our default software image contains 3 partitions:


{|class=wikitable
{|class=wikitable
Line 545: Line 545:




This platform includes an eMMC device, a soldered down MMC flash device.  Our off the shelf builds are 4GiB, but up to 64GiB are available for customized builds.  The eMMC flash appears to Linux as an SD card at /dev/mmcblk1.  Our default programming of the eMMC is the same as the SD card image for standard partitions, but includes additional boot partitions that are used by U-Boot and are not affected by the eMMC partition table.
This platform includes an eMMC device, a soldered down MMC flash device.  Our off the shelf builds are 4 GB, but up to 64 GB are available for customized builds.  The eMMC flash appears to Linux as an SD card at /dev/mmcblk1.  Our default programming of the eMMC is the same as the SD card image for standard partitions, but includes additional boot partitions that are used by U-Boot and are not affected by the eMMC partition table.


The eMMC module has a similar concern by default to SD cards in that they should not be powered down during a write/erase cycle.  However, this eMMC module includes support for setting a fuse for a "Write Reliability" mode, and a "psuedo SLC (pSLC)" mode.  With both of these enabled all writes will be atomic to 512 B and each NAND cell will be treated as a single layer rather than a multi-layer cell.  If a sector is being written during a power loss, a block is guaranteed to have either the old or new data.  Even in cases where the wrong data is present on the next boot, fsck is often able to deal with the older data being present in a 512 B block.  The downsides to setting these modes are that it will reduce the overall write speed and halve the available space on the eMMC to roughly 1.759 GiB.  Please note that even with these settings, Technologic Systems strongly recommends designing the end application to eliminate any situations where a power-loss event can occur while any disk is mounted as read/write.  The [[##SuperCaps|TS-SILO option]] for the TS-7553-V2 can help to eliminate the dangerous situation.
The eMMC module has a similar concern by default to SD cards in that they should not be powered down during a write/erase cycle.  However, this eMMC module includes support for setting a fuse for a "Write Reliability" mode, and a "psuedo SLC (pSLC)" mode.  With both of these enabled all writes will be atomic to 512 B and each NAND cell will be treated as a single layer rather than a multi-layer cell.  If a sector is being written during a power loss, a block is guaranteed to have either the old or new data.  Even in cases where the wrong data is present on the next boot, fsck is often able to deal with the older data being present in a 512 B block.  The downsides to setting these modes are that it will reduce the overall write speed and halve the available space on the eMMC to roughly 1.759 GB.  Please note that even with these settings, Technologic Systems strongly recommends designing the end application to eliminate any situations where a power-loss event can occur while any disk is mounted as read/write.  The [[#SuperCaps|TS-SILO option]] for the TS-7553-V2 can help to eliminate the dangerous situation.


The mmc-utils package is used to enable these modes.  The command is pre-installed on the latest image.  Additionally we have created a script to safely enable the write reliability and pSLC modes.  Since the [[#U-Boot|U-Boot binary and environment]] reside on the eMMC, care must be taken to save the current state of the boot partitions, enable the modes, restore the boot partitions, and re-enable proper booting options.  This script can be used in combination with the [[#Production_Mechanism|production mechanism scripting]] to complete these steps as part of an end application production process.
The "mmc-utils" package is used to enable these modes.  The command is pre-installed on the latest image.  Additionally we have created a script to safely enable the write reliability and pSLC modes.  Since the [[#U-Boot|U-Boot binary and environment]] reside on the eMMC, care must be taken to save the current state of the boot partitions, enable the modes, restore the boot partitions, and re-enable proper booting options.  This script can be used in combination with the [[#Production_Mechanism|production mechanism scripting]] to complete these steps as part of an end application production process.





Revision as of 14:16, 11 July 2019

TS-7553-V2
ts-7553-v2.gif
Product Page
Documentation
Schematic
Mechanical Drawing
FTP Path
Processor
NXP i.MX6UL
528MHz or 696MHz
i.MX6UL Product Page
CPU Documentation

Overview

The TS-7553-V2 is a small embedded platform with an NXP i.MX6UL 696 MHz CPU with 512 MB DDR3 RAM. It is a spiritual successor to our TS-7553, using the same form factor and base features, but providing a more powerful CPU and many new features for overall better performance. The TS-7553-V2 can be ordered with soldered down WiFi with built in Bluetooth, our TS-SILO super capacitor technology for safe shutdown upon power loss, non-volatile FRAM for 2 KiB of storage. There is also support for USB Gadget via the front USB B socket, an internal USB host port, support for our monochrome LCD and 4 button membrane keypad, and eMMC flash for a vast improvement over the TS-7553's NAND.

Getting Started

A Linux PC is recommended for development, and will be assumed for this documentation. For users in Windows or OSX we recommend virtualizing a Linux PC. Most of our platforms run Debian and if there is no personal distribution preference this is what we recommend for ease of use.

Virtualization

Suggested Linux Distributions

It may be possible to develop using a Windows or OSX system, but this is not supported. Development will include accessing drives formatted for Linux and often Linux based tools.

Booting up the board

WARNING: Be sure to take appropriate Electrostatic Discharge (ESD) precautions. Disconnect the power source before moving, cabling, or performing any set up procedures. Inappropriate handling may cause damage to the board.

The TS-7553-V2 has an input voltage range of 5 V to 28 V DC through the main power connector which offers screw terminals for secure wiring or a barrel jack. The TS-7553-V2 will require approximately 1 W at idle. An ideal power supply for the TS-7553-V2 will allow up to 5W to power additional peripherals without issue. See the Specifications section for more information on power input.

Once power has been applied, output will be available on the serial console. The next section of the manual provides information on getting the console port set up. The first output is from the bootrom and will look like the following:

U-Boot 2016.03-00305-g75344a5 (Dec 15 2017 - 13:53:14 -0800)

CPU:   Freescale i.MX6UL rev1.1 at 396 MHz
Reset cause: POR
Board: Technologic Systems TS-7553-V2
I2C:   ready
DRAM:  512 MiB
MMC:   FSL_SDHC: 0, FSL_SDHC: 1
*** Warning - bad CRC, using default environment

Net:   FEC0 [PRIME]
Booting from the SD card ...
** File not found /boot/boot.ub **
34511 bytes read in 162 ms (208 KiB/s)
5460520 bytes read in 391 ms (13.3 MiB/s)
NO CHRG jumper is set, not waiting
Kernel image @ 0x80800000 [ 0x000000 - 0x535228 ]
## Flattened Device Tree blob at 83000000
   Booting using the fdt blob at 0x83000000
   Using Device Tree in place at 83000000, end 8300b6ce

Starting kernel ...



Welcome to Debian GNU/Linux 8 (jessie)!

[ SKIP ] Ordering cycle found, skipping D-Bus System Message Bus Socket
         Expecting device dev-ttymxc0.device...
[  OK  ] Reached target Remote File Systems (Pre).
...
[  OK  ] Started Update UTMP about System Runlevel Changes.

Debian GNU/Linux 8 ts-imx6ul ttymxc0

ts-imx6ul login:


The U-Boot build date reflects when U-Boot was built and serves as a revision indicator. A change to the kernel or filesystem will not affect this date.

Get a Console

Serial Console

The TS-7553-V2 includes a USB device port, this uses a 8051 based microcontroller to create a serial device on a host PC. The serial console is provided through this port at 115200 baud, 8n1, with no flow control. The USB serial device is a CP210x Virtual COM Port. Most operating systems have built-in support for this device. If not however, drivers are available for the device here.


Console from Linux

There are many serial terminal applications for Linux, three common used applications are 'picocom', 'screen', and 'minicom'. These examples demonstrate all three applications and assume that the serial device is "/dev/ttyUSB0" which is common for USB adapters. Be sure to replace the serial device string with that of the device on your workstation.

'picocom' is a very small and simple client.

picocom -b 115200 /dev/ttyUSB0

For Rev C hardware or newer.

picocom -b 115200 /dev/ttyACM0


'screen' is a terminal multiplexer which happens to have serial support.

screen /dev/ttyUSB0 115200

For Rev C hardware or newer.

screen /dev/ttyACM0 115200


Or a very commonly used client is 'minicom' which is quite powerful but requires some setup:

minicom -s
  • Navigate to 'serial port setup'
  • Type "a" and change location of serial device to '/dev/ttyUSB0' then hit "enter"
  • If needed, modify the settings to match this and hit "esc" when done:
     E - Bps/Par/Bits          : 115200 8N1
     F - Hardware Flow Control : No
     G - Software Flow Control : No
  • Navigate to 'Save setup as dfl', hit "enter", and then "esc"


Console from Windows

Putty is a small simple client available for download here. Open up Device Manager to determine your console port. See the putty configuration image for more details.

On boards using the Silabs CP210x driver:

Device Manager Putty Configuration

On boards using the Renesas USB CDC-ACM driver:

Device Manager 2 Putty Configuration 2

U-Boot

This platform includes U-Boot as the bootloader to load and boot the full operating system. The i.MX6UL processor loads U-Boot from the eMMC flash at power-on. U-Boot allows booting images from the microSD, eMMC, NFS, or USB. U-Boot is a general purpose bootloader that is capable of booting into common Linux distributions, Android, QNX, or others.

On a normal boot, output from U-Boot will be similar to the following:

U-Boot 2016.03-00305-g75344a5 (Dec 15 2017 - 13:53:14 -0800)

CPU:   Freescale i.MX6UL rev1.1 at 396 MHz
Reset cause: WDOG
Board: Technologic Systems TS-7553-V2
I2C:   ready
DRAM:  512 MiB
MMC:   FSL_SDHC: 0, FSL_SDHC: 1
Net:   FEC0 [PRIME]
Booting from the SD card ...
** File not found /boot/boot.ub **
34511 bytes read in 162 ms (208 KiB/s)
5460520 bytes read in 391 ms (13.3 MiB/s)
NO CHRG jumper is set, not waiting
Kernel image @ 0x80800000 [ 0x000000 - 0x535228 ]
## Flattened Device Tree blob at 83000000
   Booting using the fdt blob at 0x83000000
   Using Device Tree in place at 83000000, end 8300b6ce

Starting kernel ...


By default the board will boot to SD or eMMC depending on the status of the "SD Boot" jumper on startup.

Entering U-Boot shell

The U-Boot shell is a powerful tool. It allows modification of the environment, as well as the ability to run commands directly. By default, there are two ways to enter the shell: Set the U-Boot jumper, or press and hold the Push Switch before applying power and hold it for 5 seconds. When entering the U-Boot shell, it will attempt to run a script on a USB mass storage device before finally dropping to the shell.

The reset switch is provided as a convenience, so U-Boot can be entered without having to open any kind of enclosure. It can also be disabled for security purposes. Even if the switch is disabled, the U-Boot shell can still be accessed by using the U-Boot jumper.

To disable the press-and-hold method of entering the U-Boot shell, use the following U-Boot commands:

env set rstuboot 0
env save

By setting the env var, rstuboot, to a 1, the push-and-hold method can be re-enabled.

U-Boot Environment

The eMMC flash contains both the U-Boot executable binary and U-Boot environment. Our default build has 2 MiB of environment space which can be used for variables and boot scripts. The following commands are examples of how to manipulate the U-Boot environment:

# Print all environment variables
env print -a

# Sets the variable bootdelay to 5 seconds
env set bootdelay 5;

# Variables can also contain commands
env set hellocmd 'led red on; echo Hello world; led green on;'

# Execute commands saved in a variable
env run hellocmd;

# Commit environment changes to the SPI flash
# Otherwise changes are lost
env save

# Restore environment to default
env default -a

# Remove a variable
env delete emmcboot

U-Boot Commands

# The most important command is 
help
# This can also be used to see more information on a specific command
help i2c

# This is a command added to U-Boot by TS to read the baseboard ID on our 
# System on Module devices
bbdetect
echo ${baseboard} ${baseboardid} 
# The echo will return something similar to:
# TS-8390 2

# Boots into the binary at $loadaddr.  The loaded file needs to have
# the U-Boot header from mkimage.  A uImage already contains this.
bootm
# Boots into the binary at $loadaddr, skips the initrd, specifies
# the FDT addrress so Linux knows where to find the device tree
bootm ${loadaddr} - ${fdtaddr}

# Boot a Linux zImage loaded at $loadaddr
bootz
# Boot in to a Linux zImage at $loadaddr, skip initrd, specifies
# the FDT address to Linux knows where to find the device tree
bootz ${loadaddr} - ${fdtaddr}

# Get a DHCP address
dhcp
# This sets ${ipaddr}, ${dnsip}, ${gatewayip}, ${netmask}
# and ${ip_dyn} which can be used to check if the dhcp was successful

# These commands are used for scripting:
false # do nothing, unsuccessfully
true # do nothing, successfully

# This command can set fuses in the processor
# Setting fuses can brick the unit, will void the warranty,
# and should not be done in most cases
fuse

# GPIO can be manipulated from U-Boot.  Keep in mind that the IOMUX 
# in U-Boot is only setup enough to boot the device, so not all pins will
# be set to GPIO mode out of the box.  Boot to the full operating system
# for more GPIO support.
# GPIO are specified in bank and IO in this manual.  U-Boot uses a flat numberspace,
# so for bank 2 DIO 25, this would be number (32*1)+25=89
# The formula thus being (32*(bank-1)+dio)=flattened_dio
# Note that on some products, bank 1 is the first bank
# Set 2_25 low
gpio clear 83
# Set 2_25 high
gpio set 83
# Read 2_25
gpio input 83

# Control LEDs
led red on
led green on
led all off
led red toggle

# This command is used to copy a file from most devices
# Load kernel from SD
load mmc 0:1 ${loadaddr} /boot/uImage
# Load Kernel from eMMC
load mmc 1:1 ${loadaddr} /boot/uImage
# Load kernel from USB
usb start
load usb 0:1 ${loadaddr} /boot/uImage
# Load kernel from SATA
sata init
load sata 0:1 ${loadaddr} /boot/uImage

# View the FDT from U-Boot
load mmc 0:1 ${fdtaddr} /boot/imx6q-ts4900.dtb
fdt addr ${fdtaddr}
fdt print

# It is possible to blindly jump to any memory location
# This is similar to bootm, but it does not require
# the use of the U-Boot header
load mmc 0:1 ${loadaddr} /boot/custombinary
go ${loadaddr}

# Browse fat, ext2, ext3, or ext4 filesystems:
ls mmc 0:1 /

# Access memory like devmem in Linux, read/write arbitrary memory
# using mw and md
# write
mw 0x10000000 0xc0ffee00 1
# read
md 0x10000000 1

# Test memory.
mtest

# Check for new SD card
mmc rescan
# Read SD card size
mmc dev 0
mmcinfo
# Read eMMC Size
mmc dev 1
mmcinfo

# The NFS command is like 'load', but used over the network
dhcp
env set serverip 192.168.0.11
nfs ${loadaddr} 192.168.0.11:/path/to/somefile

# Test ICMP
dhcp
ping 192.168.0.11

# Reboot
reset

# SPI access is through the SF command
# Be careful with sf commands since
# this is where U-Boot and the FPGA bitstream exist
# Improper use can render the board unbootable
sf probe

# Delay in seconds
sleep 10

# Load HUSH scripts that have been created with mkimage
load mmc 0:1 ${loadaddr} /boot/ubootscript
source ${loadaddr}

# Most commands have return values that can be used to test
# success, and HUSH scripting supports comparisons like
# test in Bash, but much more minimal
if load mmc 1:1 ${fdtaddr} /boot/uImage;
	then echo Loaded Kernel
else
	echo Could not find kernel
fi

# Commands can be timed with "time"
time sf probe

# Print U-Boot version/build information
version

Modify Linux Kernel cmdline

The Linux kernel cmdline can be customized by modifying the cmdline_append variable. If new arguments are added, the existing value should also be included with the new arguments.

env set cmdline_append rw rootwait console=ttymxc0,115200 quiet
env save

The kernel command line can also be modified from from the onboard Linux. From the linux shell prompt run the following commands to install the necessary tools and create the script:

apt-get update && apt-get install u-boot-tools -y
echo "env set cmdline_append rw rootwait console=ttymxc0,115200 quiet" > /boot/boot.scr
mkimage -A arm -T script -C none -n 'tsimx6ul boot script' -d /boot/boot.scr /boot/boot.ub

The boot.scr includes the plain text commands to be run in U-Boot on startup. The mkimage tool adds a checksum and header to this file which can be loaded by U-Boot. The .ub file should not be edited directly.

Booting From NFS

U-Boot's NFS support can be used to load a kernel, device tree binary, and root filesystem. The default scripts include an example NFS boot script. Because of the way U-Boot tries to infer server data, the script we use will bypass this, making it more straightforward to use an NFS root that will not be heavily dependent on a particular network configuration.

# Set this to your NFS server IP and NFS directory path
env set nfsroot 192.168.0.1:/path/to/nfs/rootfs/
env save

To boot your NFS root:

# Boot to NFS once
run nfsboot;

# To make the NFS boot the persistent default
env set bootcmd run nfsboot;
env save
Note: If 'bootcmd' is used to test for whether the system should stop at the U-Boot shell or continue, the above will make it difficult to get back to the U-Boot shell as it will always attempt to boot regardless of jumper status.

Booting From USB

By default, U-Boot will attempt to read a U-Boot script from a USB drive when the U-Boot jumper is set (or the reset button is enabled and depressed). It copies /tsinit.ub into memory and jumps in to the script. To make a bootable drive, create a single ext4 partition on a USB drive and unpack the rootfs tarball located here

The one addition is to create the tsinit.ub file in the root of the USB drive. In order to do this, a U-Boot script must be created and then converted to the .ub format. This process requires a set of U-Boot specific tools. These are available on most every linux distribution, the instructions below are for Debian, either run on a host PC or on the device itself. See the package installation documentation for other respective distributions.

Install U-Boot tools in Debian

apt-get update && apt-get install u-boot-tools -y

Create the file tsinit.scr in the root of the USB drive with the linux filesystem:

# Prepare with:
# mkimage -A arm -T script -C none -n 'ts7553v2 usb' -d tsinit.scr tsinit.ub

# DO NOT MANUALLY EDIT THE .UB FILE

load usb 0:1 ${fdtaddr} /boot/imx6ul-ts7553v2${variant}.dtb;

load usb 0:1 ${loadaddr} /boot/zImage;

setenv bootargs root=/dev/sda1 ${cmdline_append};
bootz ${loadaddr} - ${fdtaddr};

Then in the same directory generate the tsinit.ub file:

mkimage -A arm -T script -C none -n 'ts7553v2 usb' -d tsinit.scr tsinit.ub

Update U-Boot

WARNING: Installing a custom U-Boot is not recommended and may cause the device to fail to boot.

The latest U-Boot binary can be downloaded from the TS-7553-V2 FTP site. Copy this file to /boot/u-boot.imx on the 1st partition of the SD card. The U-Boot binary can be updated by inserting that SD card in to the TS-7553-V2, setting the U-Boot and SD card jumpers, and powering up the unit. At the U-Boot prompt, the following command can be used:

run update-uboot

The above script will use the /boot/u-boot.imx file from the SD card or eMMC, depending on the state of the SD Boot jumper.

U-Boot Development

We do provide our U-Boot sources, but we do not recommend rebuilding a custom U-Boot binary as it can leave the system in an unbootable state.

If you still want to proceed with building a custom U-Boot, use the "tsimx_v2016.03_4.1.15_2.0.0_ga" branch from the github here: https://github.com/embeddedTS/u-boot-imx

When compiling, we recommend using ONLY this cross-compiler, the use of any other compiler may cause issues. Specifically, we have experienced RAM problems when using a more recent cross compiler to build this version of U-Boot. The use of any other compiler may leave the system in an unbootable state!

export ARCH=arm
export CROSS_COMPILE=/path/to/folder/bin/arm-tsimx6ul-linux-gnueabihf-

make ts7553v2_defconfig
make u-boot.imx

This will output a u-boot.imx that can be written to the device using the steps in Update U-Boot.

POST

The TS-7553-V2 includes a simple POST test. This is normally used in production to verify basic functionality rapidly before doing more thorough testing. By default, this is not enabled on every boot, but it can be added via U-Boot scripting if there is a need for additional confidence in the application. The POST test quickly verifies basic functionality of: USB, RTC, Ethernet PHY, FRAM (if present), WiFi/BT module (if present), eMMC (see warning below), RAM, and the supervisory microcontroller.

The post test can be run with the following command in U-Boot:

post
WARNING: The 'post' command has an optional "-d" argument; when this argument is passed it does a write and readback test of the eMMC and FRAM which is DESTRUCTIVE to the data on the disk! Note that it will not modify the boot sector contents of the eMMC. The eMMC chip is still tested for basic functionality without the argument passed, but no data is read or written from the disk itself.

Debian

For development, it is recommended to work directly in Debian on the SD card. Debian provides many more packages and a much more familiar environment for users already versed in Debian. Through Debian it is possible to configure the network, use the 'apt-get' suite to manage packages, and perform other configuration tasks. Out of the box the Debian distribution does not have any default username/password set. The account "root" is set up with no password configured. It is possible to log in via the serial console without a password but many services such as ssh will require a password set or will not allow root login at all. It is advised to set a root password and create a user account when the unit is first booted.

Note: Setting up a password for root is only feasible on the uSD image.

It is also possible to cross compile applications. Using a Debian host system will allow for installing a cross compiler to build applications. The advantage of using a Debian host system comes from compiling against libraries. Debian cross platform support allows one to install the necessary development libraries on the host, building the application on the host, and simply installing the runtime libraries on the target device. The library versions will be the same and completely compatible with each other. See the respective Debian cross compiling section for more information.

Debian Jessie(8)

Getting Started

The stock image uses a Debian Jessie distribution and Linux kernel version 4.1.15. The latest image can be downloaded below.

This image can then be written to a microSD card or the on-board eMMC flash in order to be booted on the TS-7553-V2.

Configuring the Network

From almost any Linux system you can use 'ip' command or the 'ifconfig' and 'route' commands to initially set up the network.

# Bring up the CPU network interface
ifconfig eth0 up

# Or if you're on a baseboard with a second ethernet port, you can use that as:
ifconfig eth1 up

# Set an ip address (assumes 255.255.255.0 subnet mask)
ifconfig eth0 192.168.0.50

# Set a specific subnet
ifconfig eth0 192.168.0.50 netmask 255.255.0.0

# Configure your route.  This is the server that provides your internet connection.
route add default gw 192.168.0.1

# Edit /etc/resolv.conf for your DNS server
echo "nameserver 192.168.0.1" > /etc/resolv.conf

Most networks will offer a DHCP server, an IP address can be obtained from a server with a single command in linux:

Configure DHCP in Debian:

# To setup the default CPU ethernet port
dhclient eth0
# Or if you're on a baseboard with a second ethernet port, you can use that as:
dhclient eth1
# You can configure all ethernet ports for a dhcp response with
dhclient


Systemd provides a networking configuration option to allow for automatic configuration on startup. Systemd-networkd has a number of different configuration files, some of the default examples and setup steps are outlined below.

/etc/systemd/network/eth.network

[Match]
Name=eth*

[Network]
DHCP=yes

To use DHCP to configure DNS via systemd, start and enable the network name resolver service, systemd-resolved:

systemctl start systemd-resolved.service 
systemctl enable systemd-resolved.service
ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf


For a static config create a network configuration for that specific interface.

/etc/systemd/network/eth0.network

[Match]
Name=eth0

[Network]
Address=192.168.0.50/24
Gateway=192.168.0.1
DNS=192.168.0.1

For more information on networking, see Debian and systemd's documentation:

Wi-Fi Client

If connecting to a WPA/WPA2 network, a wpa_supplicant config file must first be created:

wpa_passphrase yournetwork yournetworkpassphrase > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf


Create the file /lib/systemd/system/wpa_supplicant@.service with these contents

[Unit]
Description=WPA supplicant daemon (interface-specific version)
Requires=sys-subsystem-net-devices-%i.device
After=sys-subsystem-net-devices-%i.device

[Service]
Type=simple
ExecStart=/sbin/wpa_supplicant -c/etc/wpa_supplicant/wpa_supplicant-%I.conf -i%I

[Install]
Alias=multi-user.target.wants/wpa_supplicant@%i.service


Create the file /etc/systemd/network/wlan0.network with:

[Match]
Name=wlan0

[Network]
DHCP=yes

See the systemctl-networkd example for setting a static IP for a network interface. The wlan0.network can be configured the same way as an eth.network.


To enable all of the changes that have been made, run the following commands:

systemctl enable wpa_supplicant@wlan0
systemctl start wpa_supplicant@wlan0
systemctl restart systemd-networkd

Host a Wi-Fi Access Point

This section will discuss setting up the WiFi device as an access point that is bridged to an ethernet port. That is, clients can connect to the AP and will be connected to the ethernet network through this network bridge. The ethernet network must provide a DHCP server; this will be passed through the bridge to WiFi client devices as they connect.

It is also possible to run a DHCP client on the platform itself. In this case the hostapd.conf file needs to be set up without bridging and a DHCP server needs to be configured. Refer to Debian's documentation for more details on DHCP server configuration.

The 'hostapd' utility is used to manage the access point of the device. This is usually installed by default, but can be installed with:

apt-get update && apt-get install hostapd -y


Note: The install process may start an unconfigured 'hostapd' process. This process must be killed before moving forward.


Modify the file "/etc/hostapd/hostapd.conf" to have the following lines:

ssid=YourWiFiName
wpa_passphrase=Somepassphrase
interface=wlan0
bridge=br0
auth_algs=3
channel=7
driver=nl80211
hw_mode=g
logger_stdout=-1
logger_stdout_level=2
max_num_sta=5
rsn_pairwise=CCMP
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP CCMP
Note: Refer to the kernel's hostapd documentation for more wireless configuration options.


The access point can be started and tested by hand:

hostapd /etc/hostapd/hostapd.conf


Systemd auto-start with bridge to eth0

It is possible to configure the auto-start of 'hostapd' through systemd. The configuration outlined below will set up a bridge with "eth0", meaning the Wi-Fi connection is directly connected to the ethernet network. The ethernet network is required to have a DHCP server present and active on it to assign Wi-Fi clients an IP address. This setup will allow Wi-Fi clients access to the same network as the ethernet port, and the bridge interface will allow the platform itself to access the network.


Set up hostapd

First, create the file "/etc/systemd/system/hostapd_user.service" with the following contents:

[Unit]
Description=Hostapd IEEE 802.11 AP
Wants=network.target
Before=network.target
Before=network.service
After=sys-subsystem-net-devices-wlan0.device
After=sys-subsystem-net-devices-br0.device
BindsTo=sys-subsystem-net-devices-wlan0.device
BindsTo=sys-subsystem-net-devices-br0.device

[Service]
Type=forking
PIDFile=/run/hostapd.pid
ExecStart=/usr/sbin/hostapd /etc/hostapd/hostapd.conf -P /run/hostapd.pid -B

[Install]
WantedBy=multi-user.target

Then enable this in systemd:

systemctl enable hostapd_user.service
systemctl enable systemd-networkd


Set up bridging

Create the following files with the listed contents.


"/etc/systemd/network/br0.netdev"

[NetDev]
Name=br0
Kind=bridge


"/etc/systemd/network/br0.network"

[Match]
Name=br0

[Network]
DHCP=yes


"/etc/systemd/network/bridge.network"

[Match]
Name=eth0

[Network]
Bridge=br0

Cellular Data Network

DC-TS767-MT MultiTech Modem

The TS-7553-V2 includes support for the Multitech MTSMC-G2 or MTSMC-H5 connected via the TS-DC767-MT daughter card, which can connect to the internet using pppd. The modem is attached to the HD1 Header, also called the Daughter Card interface. The modem itself can be configured with the following commands:

ln -s /dev/ttymxc6 /dev/ttymultidc


There are two GPIO pins that can control reset and RTS of the cell modem. These two pins default to an I2C mode, so before they can be used, they must have the pinmux set to GPIO. This can be done with the following two commands:

peekpoke 32 0x20e0118 0x5  #Set RTS pin to GPIO, GPIO 69
peekpoke 32 0x20e011c 0x5  #Set reset pin to GPIO, GPIO 70


The DIO pins can be controlled now from the linux GPIO subsystem. In order to function properly, the RTS pin must be low, and the reset must be high. This can be done with the following commands:

echo "69" > /sys/class/gpio/export
echo "70" > /sys/class/gpio/export
echo "low" > /sys/class/gpio/gpio69/direction
echo "high" > /sys/class/gpio/gpio70/direction


The pppd application must be installed and any required modules loaded:

apt-get update && apt-get install -y ppp

This example is configured for T-Mobile in the US:

/etc/ppp/peers/tmobile


/dev/ttymultidc
noauth
115200
debug
usepeerdns
persist
defaultroute

connect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile"
disconnect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile-disconnect"

/etc/ppp/chatscripts/tmobile

TIMEOUT 10
ABORT 'BUSY'
ABORT 'NO ANSWER'
ABORT 'ERROR'

"" "\p\p\p\p\p\p\p\p\p\p\p\p+++\p\p\p\p\p\p\p\p\p\p\p\p"
"" "ATH0"

"OK" 'AT+CGDCONT=1,"IP","wap.voicestream.com"'

ABORT 'NO CARRIER'
OK 'ATD*99***1#'
CONNECT

/etc/ppp/chatscripts/tmobile-disconnect

"" "\K"
"" "+++ATH0"

Using a different carrier you will likely only need to replace wap.voicestream.com with the access point for your carrier.

To start pppd:

pppd call tmobile

# Or for more logging information:
# pppd nodetach call tmobile

This will create a ppp0 interface that can now be used as a standard network interface, and should set up a default route to the internet. For other carriers, typically you will only need a different access point listed in the AT+CGDCONT call, but further adjustments may be necessary.


Note: We have observed that the MTSMC-H5 connected to some networks has issues at or below 115200 baud. The issues observed are connection timeouts with the network itself. The connection between the modem and host device remain rock solid. While many applications are tolerant to the connection being reset, we have found some network downloads will abort without being able to recover. Running the unit at a faster baud rate, 230400 or higher, has been observed to eliminate this issue entirely. This does mean, however, that every time the device is started up, the modem must be issued an AT+IPR command (as noted below) at 115200 baud, then pppd started with the matched and higher baud rate in the peer script as shown above.


Faster Data Rates

While the MTSMC-G2 (GPRS) is limited to 115200 baud, the MTSMC-H5 (HDSPA) can communicate over serial up to 921600 allowing actual transfer rates around 80-90KB/s.

To set a custom baudrate in Linux, the method depends on the CPU and kernel support. More recent UART peripherals have a higher clock and a smarter driver, and can therefore use custom baud rates inherently. However, some systems require the use of 'setserial' using the spd_cust flag and some manual settings. When the spd_cust baud rate is set, Linux will re-purpose 38400 baud to use the set custom baud rate.


First, test the unit to see if it is possible to open up the UART with a higher baud rate:

picocom -b 921600 /dev/ttymultidc

If the higher baud is unsupported, picocom will return a failure similar to the following:

FATAL: failed to add device /dev/ttymultidc: Invalid baud rate

If the above error is received, then the method below using setserial must be used.

Otherwise, the port can be closed, re-opened at 115200 baud to communicate with the modem, and then the following command can be used to tell the cell modem to enter a higher baud rate:

AT+IPR=921600

Now the port can be closed everything will function at the higher baud rate. Be sure to update the providers file. Using the example T-Mobile configuration, edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).


Common Baud Rates
Divisor Rate
1 921600
2 460800
3 307200
4 230400
5 184320
6 153600
7 131657
8 115200

Larger divisors will also work, but this should cover the common range. Using the setserial command you can specify the divisor. For example, to reach 115200 with the alternative baud base:

setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 8

Next you will need to tell the modem to communicate at the faster baud rates. You can use a client like picocom or minicom to connect directly to the modem to send it commands.

picocom -b 38400 /dev/ttymultidc

Even though we are talking at 115200, 38400 must be specified since we are using a custom baud_base. You can test communication with the modem again by typing "AT", pressing enter, and receiving "OK". To reconfigure the modem to the faster 921600 baud rate you can send it this command:

AT+IPR=921600

This will respond with OK, but now you will need to quit out of picocom (ctrl a,x) and reconfigure the baud base to use divisor 1:

setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 1

The only change now needed is in your providers file. Using the example T-Mobile configuration , edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).


Troubleshooting

If you are not able to obtain a ppp connection there are a few values you can check:

Troubleshooting: Cell Signal

Make sure ppp is not running, and execute these commands to check the signal strength.

stty raw -echo speed 115200 -F /dev/ttymultidc 
cat /dev/ttymultidc &
echo -e "AT+CSQ\r\n" > /dev/ttymultidc 
killall cat

The return value should be something like "+CSQ: 9,2", or with no connection, +CSQ: 99,99. The second argument is the signal strengh which follows this table:

RSSI return values
0 -113 dBm or less
1 -111 dBm
2 to 30 -109 to -53dBm
31 -51dBm or greater
99 not known or detectable

If you return 99, make sure the antenna is connected and that you are in an area with good signal from your provider. Even without a valid SIM card you can have a good connection. If you are in another country, you may need to adjust the band for those supported by your carrier. The default value is appropriate for most US based carriers. Refer to the +WMBS command in your AT command guide for more options.


Troubleshooting: SIM card

If you have a good signal strength but are not obtaining a connection you can verify that the modem is able to read the subscriber number. This proves your SIM card is valid.

stty raw -echo speed 115200 -F /dev/ttymultidc 
cat /dev/ttymultidc &
echo -e "AT+CNUM\r\n" > /dev/ttymultidc 
killall cat

With a valid SIM this will return something like:

+CNUM: "","12345678901",129

If the SIM not detected you will only read ERROR. Make sure in this case that the card is inserted in the right direction so the pads on the card line up with the socket.

Troubleshooting: Other Options

If neither of the above steps get you connected you may want to contact your service provider for more information about where your connection attempts are failing.

NimbeLink Skywire modem

The CN5 XBee Socket is able to support NimbeLink Skywire Embedded modems. Information on setting up and configuring the power and USB interface for Skywire modules can be found here. Please note that there are various models of the Skywire modules that all support different interfaces. These include cdc_ether, cdc_ncm, USB serial, and a simple TTL UART. Both the USB ethernet and NCM interfaces present a network device to the system, while the USB serial and UART interfaces require PPP to manage the connection.

Please see the NimbeLink documentation for the specific module in use for more detailed information on establishing connection with a cellular network via the modem.

Debian Application Development

Debian Jessie Cross Compiling

Debian Jessie previously provided cross compilers via the Emdebian project. However, Emdebian has been unmaintained for a number of years and is no longer able to provide a viable install package. In order to cross compile from a Debian Jessie workstation, a third party cross compiler is required.

A Debian Jessie install on a workstation has the ability to build for the same release on other architectures using Debian binary libraries. A PC, virtual machine, or chroot will need to be used for this. Install Debian Jessie for your workstation here.

From a Debian workstation (not the target), run the following commands to set up the cross compiler. Note that this expects a 64-bit Debian Jessie install on the workstation. 32-bit installations are not supported at this time.

# Run "lsb_release -a" and verify Debian 8.X is returned.  These instructions are not
# expected to work on any other version or distribution.

cd ~
wget http://ftp.embeddedTS.com/ftp/ts-arm-sbc/ts-7553-V2-linux/cross-toolchains/gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz
# The above toolchain is from Linaro. Other cross compilers can be used but have not been tested.
mkdir cross_compiler
tar xvf gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf.tar.xz -C ~/cross_compiler
export PATH=$PATH:~/cross_compiler/gcc-linaro-4.9-2016.02-x86_64_arm-linux-gnueabihf/bin/
# The 'export' command needs to be run every time the user logs in. It is possible to add this command to the user's ".bashrc" file
# in their home directory to ensure it is automatically run every time the user is logged in.
su root
dpkg --add-architecture armhf
apt-get update
apt-get install build-essential

This will install a toolchain that can be used with the prefix "arm-linux-gnueabihf-". The standard GCC tools will start with that name, eg "arm-linux-gnueabihf-gcc".

The toolchain can now compile a simple hello world application. Create hello-world.c on the Debian workstation:

#include <stdio.h>
int main(){
    printf("Hello World\n");
}

To compile this:

arm-linux-gnueabihf-gcc hello-world.c -o hello-world
file hello-world

This will return that the binary created is for ARM. Copy this to the target platform to run it there.

Debian Jessie supports multiarch which can install packages designed for other architectures. On workstations this is how 32-bit and 64-bit support is provided. This can also be used to install armhf packages on an x86 based workstation.

This cross compile environment can link to a shared library from the Debian root. The package would be installed in Debian on the workstation to provide headers and ".so" files. This is included in most "-dev" packages. When run on the arm target it will also need a copy of the library installed, but it does not need the -dev package. Note that since the cross compiler used is 3rd party and not directly from Debian, some compile commands that include libraries will need additional arguments to tell the compiler and linker where on the workstation to find the necessary headers and libraries. Usually, the additional arguments will look like the following string, however adjustments may need to be made depending on the application.

 -I/usr/include -L/usr/lib/arm-linux-gnueabihf -L/lib/arm-linux-gnueabihf -Wl,-rpath=/usr/lib/arm-linux-gnueabihf,-rpath=/lib/arm-linux-gnueabihf


apt-get install libcurl4-openssl-dev:armhf

# Download the simple.c example from curl:
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
# After installing the supporting library, curl will link as compiling on the unit.
arm-linux-gnueabihf-gcc -I/usr/include -L/usr/lib/arm-linux-gnueabihf -L/lib/arm-linux-gnueabihf -Wl,-rpath=/usr/lib/arm-linux-gnueabihf,-rpath=/lib/arm-linux-gnueabihf simple.c -o simple -lcurl

Copy the binary to the target platform and run on the target. This can be accomplished with network protocols like NFS, SCP, FTP, etc.

If any created binaries do not rely on hardware support like GPIO or CAN, they can be run using qemu.

# using the hello world example from before:
./hello-world
# Returns Exec format error
apt-get install qemu-user-static
./hello-world

Installing New Software

Debian provides the apt-get system which allows management of pre-built applications. The apt tools require a network connection to the internet in order to automatically download and install new software. The update command will download a list of the current versions of pre-built packages.

Older Debian releases are moved to a different server to indicate it is no longer getting security updates. To download packages for these older distributions, edit /etc/apt/sources.list to only have the following lines:

Jessie:

deb http://archive.debian.org/debian/ jessie main
deb-src http://archive.debian.org/debian/ jessie main

Wheezy:

deb http://archive.debian.org/debian/ wheezy main
deb-src http://archive.debian.org/debian/ wheezy main

After modifying that file, be sure to update the package list:

apt-get update

A common example is installing Java runtime support for a system. Find the package name first with search, and then install it.

root@ts:~# apt-cache search openjdk
jvm-7-avian-jre - lightweight virtual machine using the OpenJDK class library
freemind - Java Program for creating and viewing Mindmaps
icedtea-7-plugin - web browser plugin based on OpenJDK and IcedTea to execute Java applets
default-jdk - Standard Java or Java compatible Development Kit
default-jdk-doc - Standard Java or Java compatible Development Kit (documentation)
default-jre - Standard Java or Java compatible Runtime
default-jre-headless - Standard Java or Java compatible Runtime (headless)
jtreg - Regression Test Harness for the OpenJDK platform
libreoffice - office productivity suite (metapackage)
icedtea-7-jre-jamvm - Alternative JVM for OpenJDK, using JamVM
openjdk-7-dbg - Java runtime based on OpenJDK (debugging symbols)
openjdk-7-demo - Java runtime based on OpenJDK (demos and examples)
openjdk-7-doc - OpenJDK Development Kit (JDK) documentation
openjdk-7-jdk - OpenJDK Development Kit (JDK)
openjdk-7-jre - OpenJDK Java runtime, using Hotspot Zero
openjdk-7-jre-headless - OpenJDK Java runtime, using Hotspot Zero (headless)
openjdk-7-jre-lib - OpenJDK Java runtime (architecture independent libraries)
openjdk-7-source - OpenJDK Development Kit (JDK) source files
uwsgi-app-integration-plugins - plugins for integration of uWSGI and application
uwsgi-plugin-jvm-openjdk-7 - Java plugin for uWSGI (OpenJDK 7)
uwsgi-plugin-jwsgi-openjdk-7 - JWSGI plugin for uWSGI (OpenJDK 7)
                                                       

In this case you will want the openjdk-7-jre package. Names of packages are on Debian's wiki or the packages site.

With the package name apt-get install can be used to install the prebuilt packages.

apt-get install openjdk-7-jre
# More than one package can be installed at a time.
apt-get install openjdk-7-jre nano vim mplayer

For more information on using apt-get refer to Debian's documentation here.

Setting up SSH

To install ssh, install the package as normal with apt-get:

apt-get install openssh-server


Make sure the device is configured on the network and set a password for the remote user. SSH will not allow remote connections without a password or a valid SSH key pair.

passwd root
Note: The default OpenSSH server will not permit root to login via SSH as a security precaution. To allow root to log in via ssh anyway, edit the /etc/ssh/sshd_config file and add the line PermitRootLogin yes in the authentication section. This change will take effect after reboot or after sshd service restart.

After this setup it is now possible to connect from a remote PC supporting SSH. On Linux/OS X this is the "ssh" command, or from Windows using a client such as PuTTY.

Note: If a DNS server is not present on the target network, it is possible to save time at login by adding "UseDNS no" in /etc/ssh/sshd_config.

Starting Automatically

A systemd service can be created to start up headless applications. Create a file in /etc/systemd/system/yourapp.service

[Unit]
Description=Run an application on startup

[Service]
Type=simple
ExecStart=/usr/local/bin/your_app_or_script

[Install]
WantedBy=multi-user.target

If networking is a dependency add "After=network.target" in the Unit section. Once you have this file in place add it to startup with:

# Start the app on startup, but will not start it now
systemctl enable yourapp.service

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service
Note: See the systemd documentation for in depth documentation on services.

To start an application on bootup with X11 instead change the x-session-manager. By default the system starts xfce:

root@ts:~# ls -lah /usr/bin/x-session-manager 
lrwxrwxrwx 1 root root 35 May 26  2015 /usr/bin/x-session-manager -> /etc/alternatives/x-session-manager
root@ts:~# ls -lah /etc/alternatives/x-session-manager
lrwxrwxrwx 1 root root 19 May 26  2015 /etc/alternatives/x-session-manager -> /usr/bin/startxfce4

The x-session can be modified to only start specified processes. Create the file /usr/bin/mini-x-session with these contents:

#!/bin/bash
matchbox-window-manager -use_titlebar no &

exec xfce4-terminal

You may need to "apt-get install matchbox-window-manager." first. This is a tiny window manager which also has a few flags that simplify embedded use. Now enable this session manager and restart slim to restart x11 and show it now.

chmod a+x /usr/bin/mini-x-session
rm /etc/alternatives/x-session-manager
ln -s /usr/bin/mini-x-session /etc/alternatives/x-session-manager
service slim restart

If the x-session-manager process ever closes x11 will restart. The exec command allows a new process to take over the existing PID. In the above example xfce4-terminal takes over the PID of x-session-manager. If the terminal is closed with commands like exit the slim/x11 processes will restart.


Debian Stretch(9)

Getting Started

The stock image uses a Debian Jessie distribution and Linux kernel version 4.1.15. The latest image can be downloaded below.

This image can then be written to a microSD card or the on-board eMMC flash in order to be booted on the TS-7553-V2.

Debian Networking

By default, Debian Stretch does not configure any interfaces to be brought up or configured.

Debian can automatically set up the networking based on the contents of "/etc/network/interfaces.d/" files. For example, to enable DHCP for "eth0" by default on startup:

echo "auto eth0
iface eth0 inet dhcp" > /etc/network/interfaces.d/eth0

To set up a static IP:

echo "auto eth0
iface eth0 inet static
    address 192.168.0.50
    netmask 255.255.255.0
    gateway 192.168.0.1" > /etc/network/interfaces.d/eth0
echo "nameserver 1.1.1.1" > /etc/resolv.conf

To make this take effect immediately for either option:

service networking restart

To configure other interfaces, replace "eth0" with the other network device name. Some interfaces may use predictable interface names. For example, the traditional name for an ethernet port might be "eth1", but some devices may use "enp1s0" for PCIe, or "enx00D069C0FFEE" (the MAC address appended) for USB ethernet interfaces. Run 'ifconfig -a' or 'ip a' to get a complete list of interfaces, including the ones that are not configured.

Debian Wi-Fi Client

Wireless interfaces are also managed with configuration files in "/etc/network/interfaces.d/". For example, to connect as a client to a WPA network with DHCP. Note some or all of this software may already be installed on the target SBC.

Install wpa_supplicant:

apt-get update && apt-get install wpasupplicant -y

Run:

wpa_passphrase youressid yourpassword

This command will output information similar to:

 network={
 	ssid="youressid"
 	#psk="yourpassword"
 	psk=151790fab3bf3a1751a269618491b54984e192aa19319fc667397d45ec8dee5b
 }

Use the hashed PSK in the specific network interfaces file for added security. Create the file:

/etc/network/interfaces.d/wlan0

allow-hotplug wlan0
iface wlan0 inet dhcp
    wpa-ssid youressid
    wpa-psk 151790fab3bf3a1751a269618491b54984e192aa19319fc667397d45ec8dee5b

To have this take effect immediately:

service networking restart

For more information on configuring Wi-Fi, see Debian's guide here.

Debian Wi-Fi Access Point

This section will discuss setting up the WiFi device as an access point that is bridged to an ethernet port. That is, clients can connect to the AP and will be connected to the ethernet network through this network bridge. The ethernet network must provide a DHCP server; this will be passed through the bridge to WiFi client devices as they connect.

It is also possible to run a DHCP client on the platform itself. In this case the hostapd.conf file needs to be set up without bridging and a DHCP server needs to be configured. Refer to Debian's documentation for more details on DHCP server configuration.

The 'hostapd' utility is used to manage the access point of the device. This is usually installed by default, but can be installed with:

apt-get update && apt-get install hostapd -y


Note: The install process may start an unconfigured 'hostapd' process. This process must be killed before moving forward.


Modify the file "/etc/hostapd/hostapd.conf" to have the following lines:

ssid=YourWiFiName
wpa_passphrase=Somepassphrase
interface=wlan0
bridge=br0
auth_algs=3
channel=7
driver=nl80211
hw_mode=g
logger_stdout=-1
logger_stdout_level=2
max_num_sta=5
rsn_pairwise=CCMP
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP CCMP
Note: Refer to the kernel's hostapd documentation for more wireless configuration options.


The access point can be started and tested by hand:

hostapd /etc/hostapd/hostapd.conf


Systemd auto-start with bridge to eth0

It is possible to configure the auto-start of 'hostapd' through systemd. The configuration outlined below will set up a bridge with "eth0", meaning the Wi-Fi connection is directly connected to the ethernet network. The ethernet network is required to have a DHCP server present and active on it to assign Wi-Fi clients an IP address. This setup will allow Wi-Fi clients access to the same network as the ethernet port, and the bridge interface will allow the platform itself to access the network.


Set up hostapd

First, create the file "/etc/systemd/system/hostapd_user.service" with the following contents:

[Unit]
Description=Hostapd IEEE 802.11 AP
Wants=network.target
Before=network.target
Before=network.service
After=sys-subsystem-net-devices-wlan0.device
After=sys-subsystem-net-devices-br0.device
BindsTo=sys-subsystem-net-devices-wlan0.device
BindsTo=sys-subsystem-net-devices-br0.device

[Service]
Type=forking
PIDFile=/run/hostapd.pid
ExecStart=/usr/sbin/hostapd /etc/hostapd/hostapd.conf -P /run/hostapd.pid -B

[Install]
WantedBy=multi-user.target

Then enable this in systemd:

systemctl enable hostapd_user.service
systemctl enable systemd-networkd


Set up bridging

Create the following files with the listed contents.


"/etc/systemd/network/br0.netdev"

[NetDev]
Name=br0
Kind=bridge


"/etc/systemd/network/br0.network"

[Match]
Name=br0

[Network]
DHCP=yes


"/etc/systemd/network/bridge.network"

[Match]
Name=eth0

[Network]
Bridge=br0

Cellular Data Network

DC-TS767-MT MultiTech Modem

The TS-7553-V2 includes support for the Multitech MTSMC-G2 or MTSMC-H5 connected via the TS-DC767-MT daughter card, which can connect to the internet using pppd. The modem is attached to the HD1 Header, also called the Daughter Card interface. The modem itself can be configured with the following commands:

ln -s /dev/ttymxc6 /dev/ttymultidc


There are two GPIO pins that can control reset and RTS of the cell modem. These two pins default to an I2C mode, so before they can be used, they must have the pinmux set to GPIO. This can be done with the following two commands:

peekpoke 32 0x20e0118 0x5  #Set RTS pin to GPIO, GPIO 69
peekpoke 32 0x20e011c 0x5  #Set reset pin to GPIO, GPIO 70


The DIO pins can be controlled now from the linux GPIO subsystem. In order to function properly, the RTS pin must be low, and the reset must be high. This can be done with the following commands:

echo "69" > /sys/class/gpio/export
echo "70" > /sys/class/gpio/export
echo "low" > /sys/class/gpio/gpio69/direction
echo "high" > /sys/class/gpio/gpio70/direction


The pppd application must be installed and any required modules loaded:

apt-get update && apt-get install -y ppp

This example is configured for T-Mobile in the US:

/etc/ppp/peers/tmobile


/dev/ttymultidc
noauth
115200
debug
usepeerdns
persist
defaultroute

connect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile"
disconnect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile-disconnect"

/etc/ppp/chatscripts/tmobile

TIMEOUT 10
ABORT 'BUSY'
ABORT 'NO ANSWER'
ABORT 'ERROR'

"" "\p\p\p\p\p\p\p\p\p\p\p\p+++\p\p\p\p\p\p\p\p\p\p\p\p"
"" "ATH0"

"OK" 'AT+CGDCONT=1,"IP","wap.voicestream.com"'

ABORT 'NO CARRIER'
OK 'ATD*99***1#'
CONNECT

/etc/ppp/chatscripts/tmobile-disconnect

"" "\K"
"" "+++ATH0"

Using a different carrier you will likely only need to replace wap.voicestream.com with the access point for your carrier.

To start pppd:

pppd call tmobile

# Or for more logging information:
# pppd nodetach call tmobile

This will create a ppp0 interface that can now be used as a standard network interface, and should set up a default route to the internet. For other carriers, typically you will only need a different access point listed in the AT+CGDCONT call, but further adjustments may be necessary.


Note: We have observed that the MTSMC-H5 connected to some networks has issues at or below 115200 baud. The issues observed are connection timeouts with the network itself. The connection between the modem and host device remain rock solid. While many applications are tolerant to the connection being reset, we have found some network downloads will abort without being able to recover. Running the unit at a faster baud rate, 230400 or higher, has been observed to eliminate this issue entirely. This does mean, however, that every time the device is started up, the modem must be issued an AT+IPR command (as noted below) at 115200 baud, then pppd started with the matched and higher baud rate in the peer script as shown above.


Faster Data Rates

While the MTSMC-G2 (GPRS) is limited to 115200 baud, the MTSMC-H5 (HDSPA) can communicate over serial up to 921600 allowing actual transfer rates around 80-90KB/s.

To set a custom baudrate in Linux, the method depends on the CPU and kernel support. More recent UART peripherals have a higher clock and a smarter driver, and can therefore use custom baud rates inherently. However, some systems require the use of 'setserial' using the spd_cust flag and some manual settings. When the spd_cust baud rate is set, Linux will re-purpose 38400 baud to use the set custom baud rate.


First, test the unit to see if it is possible to open up the UART with a higher baud rate:

picocom -b 921600 /dev/ttymultidc

If the higher baud is unsupported, picocom will return a failure similar to the following:

FATAL: failed to add device /dev/ttymultidc: Invalid baud rate

If the above error is received, then the method below using setserial must be used.

Otherwise, the port can be closed, re-opened at 115200 baud to communicate with the modem, and then the following command can be used to tell the cell modem to enter a higher baud rate:

AT+IPR=921600

Now the port can be closed everything will function at the higher baud rate. Be sure to update the providers file. Using the example T-Mobile configuration, edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).


Common Baud Rates
Divisor Rate
1 921600
2 460800
3 307200
4 230400
5 184320
6 153600
7 131657
8 115200

Larger divisors will also work, but this should cover the common range. Using the setserial command you can specify the divisor. For example, to reach 115200 with the alternative baud base:

setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 8

Next you will need to tell the modem to communicate at the faster baud rates. You can use a client like picocom or minicom to connect directly to the modem to send it commands.

picocom -b 38400 /dev/ttymultidc

Even though we are talking at 115200, 38400 must be specified since we are using a custom baud_base. You can test communication with the modem again by typing "AT", pressing enter, and receiving "OK". To reconfigure the modem to the faster 921600 baud rate you can send it this command:

AT+IPR=921600

This will respond with OK, but now you will need to quit out of picocom (ctrl a,x) and reconfigure the baud base to use divisor 1:

setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 1

The only change now needed is in your providers file. Using the example T-Mobile configuration , edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).


Troubleshooting

If you are not able to obtain a ppp connection there are a few values you can check:

Troubleshooting: Cell Signal

Make sure ppp is not running, and execute these commands to check the signal strength.

stty raw -echo speed 115200 -F /dev/ttymultidc 
cat /dev/ttymultidc &
echo -e "AT+CSQ\r\n" > /dev/ttymultidc 
killall cat

The return value should be something like "+CSQ: 9,2", or with no connection, +CSQ: 99,99. The second argument is the signal strengh which follows this table:

RSSI return values
0 -113 dBm or less
1 -111 dBm
2 to 30 -109 to -53dBm
31 -51dBm or greater
99 not known or detectable

If you return 99, make sure the antenna is connected and that you are in an area with good signal from your provider. Even without a valid SIM card you can have a good connection. If you are in another country, you may need to adjust the band for those supported by your carrier. The default value is appropriate for most US based carriers. Refer to the +WMBS command in your AT command guide for more options.


Troubleshooting: SIM card

If you have a good signal strength but are not obtaining a connection you can verify that the modem is able to read the subscriber number. This proves your SIM card is valid.

stty raw -echo speed 115200 -F /dev/ttymultidc 
cat /dev/ttymultidc &
echo -e "AT+CNUM\r\n" > /dev/ttymultidc 
killall cat

With a valid SIM this will return something like:

+CNUM: "","12345678901",129

If the SIM not detected you will only read ERROR. Make sure in this case that the card is inserted in the right direction so the pads on the card line up with the socket.

Troubleshooting: Other Options

If neither of the above steps get you connected you may want to contact your service provider for more information about where your connection attempts are failing.

NimbeLink Skywire modem

The CN5 XBee Socket is able to support NimbeLink Skywire Embedded modems. Information on setting up and configuring the power and USB interface for Skywire modules can be found here. Please note that there are various models of the Skywire modules that all support different interfaces. These include cdc_ether, cdc_ncm, USB serial, and a simple TTL UART. Both the USB ethernet and NCM interfaces present a network device to the system, while the USB serial and UART interfaces require PPP to manage the connection.

Please see the NimbeLink documentation for the specific module in use for more detailed information on establishing connection with a cellular network via the modem.

Debian Application Development

Debian Stretch Cross Compiling

Debian Stretch provides cross compilers from the Debian apt repository archive for Debian Stretch. An install on a workstation can build for the same release on other architectures. A Linux desktop or laptop PC, virtual machine, or chroot will need to be used for this. Debian Stretch for a workstation can be downloaded from here.

From a Debian workstation (not the target), run these commands to set up the cross compiler:

# Run "lsb_release -a" and verify Debian 9.X is returned.  These instructions are not
# expected to work on any other version or distribution.
su root
# Not needed for the immediate apt-get install, but used
# so we can install package:armhf for cross compiling
dpkg --add-architecture armhf
apt-get update
apt-get install curl build-essential crossbuild-essential-armhf -y

This will install a toolchain that can be used with the prefix "arm-linux-gnueabihf-". The standard GCC tools will start with that name, eg "arm-linux-gnueabihf-gcc".

The toolchain can now compile a simple hello world application. Create hello-world.c on the Debian workstation:

#include <stdio.h>
int main(){
    printf("Hello World\n");
}

To compile this:

arm-linux-gnueabihf-gcc hello-world.c -o hello-world
file hello-world

This will return that the binary created is for ARM. Copy this to the target platform to run it there.

Debian Stretch supports multiarch which can install packages designed for other architectures. On workstations this is how 32-bit and 64-bit support is provided. This can also be used to install armhf packages on an x86 based workstation.

This cross compile environment can link to a shared library from the Debian root. The package would be installed in Debian on the workstation to provide headers and libraries. This is included in most "-dev" packages. When run on the arm target it will also need a copy of the library installed, but it does not need the -dev package.

apt-get install libcurl4-openssl-dev:armhf

# Download the simple.c example from curl:
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
# After installing the supporting library, curl will link as compiling on the unit.
arm-linux-gnueabihf-gcc simple.c -o simple -lcurl

Copy the binary to the target platform and run on the target. This can be accomplished with network protocols like NFS, SCP, FTP, etc.

If any created binaries do not rely on hardware support like GPIO or CAN, they can be run using 'qemu'.

# using the hello world example from before:
./hello-world
# Returns Exec format error
apt-get install qemu-user-static
./hello-world

Debian Installing New Software

Debian provides the apt-get system which allows management of pre-built applications. The apt tools require a network connection to the internet in order to automatically download and install new software. The update command will download a list of the current versions of pre-built packages.

apt-get update

A common example is installing Java runtime support for a system. Find the package name first with search, and then install it.

root@ts:~# apt-cache search openjdk
default-jdk - Standard Java or Java compatible Development Kit
default-jdk-doc - Standard Java or Java compatible Development Kit (documentation)
default-jdk-headless - Standard Java or Java compatible Development Kit (headless)
default-jre - Standard Java or Java compatible Runtime
default-jre-headless - Standard Java or Java compatible Runtime (headless)
jtreg - Regression Test Harness for the OpenJDK platform
libreoffice - office productivity suite (metapackage)
openjdk-8-dbg - Java runtime based on OpenJDK (debugging symbols)
openjdk-8-demo - Java runtime based on OpenJDK (demos and examples)
openjdk-8-doc - OpenJDK Development Kit (JDK) documentation
openjdk-8-jdk - OpenJDK Development Kit (JDK)
openjdk-8-jdk-headless - OpenJDK Development Kit (JDK) (headless)
openjdk-8-jre - OpenJDK Java runtime, using Hotspot JIT
openjdk-8-jre-headless - OpenJDK Java runtime, using Hotspot JIT (headless)
openjdk-8-jre-zero - Alternative JVM for OpenJDK, using Zero/Shark
openjdk-8-source - OpenJDK Development Kit (JDK) source files
uwsgi-app-integration-plugins - plugins for integration of uWSGI and application
uwsgi-plugin-jvm-openjdk-8 - Java plugin for uWSGI (OpenJDK 8)
uwsgi-plugin-jwsgi-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8)
uwsgi-plugin-ring-openjdk-8 - Closure/Ring plugin for uWSGI (OpenJDK 8)
uwsgi-plugin-servlet-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8)
java-package - Utility for creating Java Debian packages

In this case, the wanted package will likely be the "openjdk-8-jre" package. Names of packages can be found on Debian's wiki pages or the packages site.

With the package name apt-get install can be used to install the prebuilt packages.

apt-get install openjdk-8-jre
# More than one package can be installed at a time.
apt-get install openjdk-8-jre nano vim mplayer

For more information on using apt-get refer to Debian's documentation here.

Debian Setting up SSH

To install the SSH server, install the package with apt-get:

apt-get install openssh-server


Debian Stretch by default disallows logins directly from the user "root". Additionally, SSH will not allow remote connections without a password or valid SSH key pair. This means in order to SSH to the device, a user account must first be created, and a password set:

useradd --create-home --shell /bin/bash newuser
passwd newuser


After this setup it is now possible to connect to the device as user "newuser" from a remote PC supporting SSH. On Linux/OS X this is the "ssh" command, or from Windows using a client such as PuTTY.

Debian Starting Automatically

A systemd service can be created to start up headless applications. Create a file in /etc/systemd/system/yourapp.service

[Unit]
Description=Run an application on startup

[Service]
Type=simple
ExecStart=/usr/local/bin/your_app_or_script

[Install]
WantedBy=multi-user.target

If networking is a dependency add "After=network.target" in the Unit section. Once you have this file in place add it to startup with:

# Start the app on startup, but will not start it now
systemctl enable yourapp.service

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service
Note: See the systemd documentation for in depth documentation on services.

Buildroot Configuration

Buildroot-2018.02 Configuration

Installing Buildroot

We offer a pre-made filesystem tarball that is based on our default Buildroot configuration. It can downloaded here: ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7553-V2-linux/distributions/ts7553-V2-Buildroot-2018.02-latest.tar.xz

Using that tarball, it's possible to create a bootable microSD card and a bootable eMMC for the TS-7553-V2.

The default configuration was designed to be as close to our stock Debian distribution. This includes our ts7553v2-utils like tsmicroctl, our TS-SILO monitor daemon, drivers and firmware for the WiFi and Bluetooth module, and support for LCD + Keypad, .

Building Buildroot

Buildroot-2018.02 building intro

Configure the build:

make ts7553v2_defconfig

Buildroot-2018.02 building end

Configuring the Network

Buildroot-2018.02 Network

Installing New Software

Buildroot-2018.02 installing software

Setting up SSH

Buildroot-2018.02 setup ssh

Starting Automatically

Buildroot-2018.02 Startup Scripts

Backup / Restore

Creating A Production Image

It is usually desired to create a golden image to use for unit production after development is complete. This process can vary greatly from application to application but there are a few steps that are going to be most often wanted. These include cleaning up temporary files, removing files that should be unique and re-generated on the first boot (SSH keys, machine-id files, etc.), setting up the hostname, and so on. We have created a script that will automate most of this process and provides hooks for additional scripts to be called as well. The script is simply passed the device node of the development disk or an existing .dd file. From this, it will create a new .dd file based on the partition scheme with all modifications made to the new image. The image source is left completely untouched and is read only. The script also assumes that the last partition on the disk is the bootable linux partition. If this is not the case or there are multiple partitions that are used in the end application, the script will need to be modified in order to accommodate this fact.

Note: The script uses output from various commands. The output format of linux utilities can vary greatly from distribution to distribution, or even within versions of the distribution. It is strongly recommended to verify the final processed image contains everything necessary for the application and that all processes completed without issue.


The simplest use of the script is:

./prep_customer_image /dev/sdX <output base name>

Note that "/dev/sdX" will need to be changed accordingly. Be sure to pass the whole disk and not just a partition.

The "<output base name>" is used as the base for all files output. For example, if "TechnologicSystems-latest" was used, then the compressed tarball output would be named "TechnologicSystems-latest.tar.bz2" (or it may end with ".tar.xz" depending on the compression used by the script). If no base name is provided, then the current date is used.

Additionally, there are two hooks available in the 'prep_customer_image' script, "prep" and "post". The top of the file has two variables, `PREP_SCRIPTS=""` and `POST_SCRIPTS=""`. Adding in a space separated list of script names to those variables will cause them to be called in order. For example, setting `PREP_SCRIPTS="add_application change_hostname"` will cause the 'prep_customer_image' script to run through its initial steps, then call './add_application', then call './change_hostname', and then will continue with the rest of the script steps.

Every script for "prep" and "post" is called with a single argument, the name of the image file. This specifically will be "<output base name>.dd". At the time of calling the prep scripts, the folder "./mount_point/" will have the last partition of the image file mounted as read/write. It is not wise to modify the image file directly since it is already mounted. All of the post scripts are called after the last partition of the image file is unmounted. This can be useful for creating additional file outputs, extracting specific partition images, etc., from the image itself. We have used these hooks in the past to remove special files and create additional images for our DoubleStore based devices.

It is also possible to run this script directly on the device when booted. This can be used to take an image of eMMC for example, when booted from the SD card. We always recommend doing initial development on SD, creating an image from that on a host PC, and then transferring it to the eMMC. This process makes development and image creation faster. If using the 'prep_customer_image' script from a booted device, be sure there is enough free space as the script creates a disk image of the target disk and then copies that in to a tarball, compressing everything as the final step.

The "prep_customer_image" script can be found in the TS-7553-V2 utilities github.

microSD Card

MicroSD8GB.png Click to download the latest tarball.

Most SD cards ship with a single partition, which is ideal. However the instructions below will destroy the partition table and use 'parted' to recreate it and make a single partition. Note that any other preferred tool can be used instead, however the partition table must be "MBR" format for U-Boot to properly parse it.

Using other OSs

At this time, we're unable to provide assistance with writing SD cards for our products from non-Linux based operating systems. We acknowledge however, that there are methods to write images and files from a variety of difference operating systems. If a native installation of Linux is unavailable, we recommend using a Virtual Machine. See the Getting Started section for links to common virtualization software and Linux installation.

Using a Linux workstation

An SD card can be written to allow it to be bootable. Download the above file and write this from a Linux workstation using the information below. A USB SD adapter can be used to access the card; or if the workstation supports direct connection of SD cards, that can be used instead. Once inserted in to the workstation, it is necessary to discover which /dev/ device corresponds with the inserted SD card before the image can be written.

Option 1: using 'lsblk'


Newer distributions include a utility called 'lsblk' which allows simple identification of the intended card.

Note: This command may need to be run as the root user:
$ lsblk

NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sdY      8:0    0   400G  0 disk 
├─sdY1   8:1    0   398G  0 part /
├─sdY2   8:2    0     1K  0 part 
└─sdY5   8:5    0     2G  0 part [SWAP]
sr0     11:0    1  1024M  0 rom  
sdX      8:32   1   3.9G  0 disk 
├─sdX1   8:33   1   7.9M  0 part 
├─sdX2   8:34   1     2M  0 part 
├─sdX3   8:35   1     2M  0 part 
└─sdX4   8:36   1   3.8G  0 part

In this case the, SD card is 4GB, so sdX is the target device and already contains 4 partitions. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. Technologic Systems is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!

Option 2: Using 'dmesg'


After plugging in the device, the 'dmesg' command can be used to list recent kernel events. When inserting a USB adapter, the last few lines of 'dmesg' output will be similar to the following (note that this command may need to be run as the root user):

$ dmesg
...
scsi 54:0:0:0: Direct-Access     Generic  Storage Device   0.00 PQ: 0 ANSI: 2
sd 54:0:0:0: Attached scsi generic sg2 type 0
sd 54:0:0:0: [sdX] 3862528 512-byte logical blocks: (3.97 GB/3.84 GiB)
...

In this case, sdX is shown as a 3.97GB card with a single partition. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. Technologic Systems is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!


The instructions below use the latest stock image, but it is also possible to use this process to update the TS-7553-V2 to the Linux 4.9 kernel with Debian Stretch image.

The following commands will reformat the first partition of the SD card, and unpack the latest filesystem on there. Replace the "/dev/sdX" on the first line with the correct whole disk device node!

# Update this variable to match the specific device node as it appears on your PC!
export SD_DEV="/dev/sdX"

# Verify nothing else has this mounted
sudo umount "${SD_DEV}"1

# Remove, and re-set the partition table, ensuring there is a single partition. Additional partitions can be added, however U-Boot expects the 1st partition to have the root filesystem tarball.
sudo dd if=/dev/zero bs=512 count=1 of="${SD_DEV}"
sudo parted -s -a optimal "${SD_DEV}" mklabel msdos
sudo parted -s -a optimal "${SD_DEV}" mkpart primary ext3 0% 100%
sudo mkfs.ext3 -F "${SD_DEV}"1

# Mount, unpack filesystem tarball, and flush all cached data
sudo mkfs.ext3 "${SD_DEV}"1
sudo mkdir /mnt/sd
sudo mount "${SD_DEV}"1 /mnt/sd/
wget https://files.embeddedTS.com/ts-arm-sbc/ts-7553-V2-linux/distributions/ts7553-V2-latest.tar.bz2
sudo tar -xf ts7553-V2-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync
Note: The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. Reinsert the disk to flush the block cache completely, then run the following commands (Note that this expects to have the bash variable still set up from above):

sudo mount "${SD_DEV}"1 /mnt/sd
cd /mnt/sd/
sudo md5sum --quiet -c md5sums.txt
cd -
sudo umount /mnt/sd
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.

eMMC

U-Boot UMS (USB mass storage)

U-Boot on the TS-7553-V2 supports the "ums" command to allow the eMMC device (or SD card, or USB device for that matter) to be accessible directly on a host PC via USB mass storage. This method is generally slower than direct access from linux on the TS-7553-V2 itself, but it allows for direct updating of the flash media.

Note: It is recommended to use a host PC with a native linux install. It has been observed that some VMs fail to correctly pass-through the USB device created on the TS-7553-V2 in U-Boot for UMS.


On the TS-7553-V2, set the U-Boot jumper before applying power. Insert the USB device cable to a host PC and open the serial console. At the U-Boot prompt, run the following command:

run emmc-ums

The USB serial will immediately disconnect, and the USB mass storage device provided by the TS-7553-V2 will begin to enumerate. The following commands can then be used to set up the eMMC, and unpack the latest tarball on to it. Note that the instructions refer to /dev/sdX, please verify the correct device node that is created on the host and adjust the instructions as necessary.

# Verify nothing else has the partition mounted
umount /dev/sdX1

mkfs.ext3 /dev/sdX1
mkdir /mnt/emmc
mount /dev/sdX1 /mnt/emmc
wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7553-V2-linux/distributions/ts7553-V2-latest.tar.bz2
tar -xf ts7553-V2-latest.tar.bz2 -C /mnt/emmc
umount /mnt/emmc
sync
Note: The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. To do so, run the following commands:

mount /dev/sdX1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.

At this point, the device is unmounted and is sync'ed. The TS-7553-V2 can be turned off at this point. Be sure to disconnect the USB cable as well to ensure the system is fully powered off.

Booted from SD

These commands assume the TS-7553-V2 is booted from the SD card:

# Verify nothing else has the partition mounted
umount /dev/mmcblk1p1

mkfs.ext3 /dev/mmcblk1p1
mount /dev/mmcblk1p1 /mnt/emmc
wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7553-V2-linux/distributions/ts7553-V2-latest.tar.bz2
tar -xf ts7553-V2-latest.tar.bz2 -C /mnt/emmc
umount /mnt/emmc
sync
Note: The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. To do so, run the following commands:

mount /dev/mmcblk1p1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync

The md5sum command will report what differences there are, if any, and return if it passed or failed.

Compile the Kernel

Linux 4.1.15 (stock)

The stock image includes a 4.1.15 kernel meant to be used with Debian Jessie. The latest software image is a tarball that contains the kernel binaries and Debian Jessie filesystem. For adding new support to the kernel, or recompiling with more specific options you will need to have a compatible Linux workstation available that can handle the cross compiling. Compiling the kernel on the device is not supported or recommended.

Prerequisites

A cross compiler is necessary, for recent Debian distributions, please follow the Debian Jessie cross compiling instructions to install a compatible cross compiler.

For other distributions, please refer to their documentation to find equivalent tools.

Additionally, some libraries and tools are required for the kernel build process:

# Install dependencies for kernel build
# The following command is for Ubuntu / Debian workstations. If using a different
# distribution, please consult distribution docs for the proper commands to install
# new packages/tools/libraries/etc.
apt-get install libncurses5-dev bc lzop


Download sources and configure

git clone https://github.com/embeddedTS/linux-tsimx
cd linux-tsimx
git checkout ts-imx_4.1.15_2.0.0_ga

# These next commands set up some necessary environment variables
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export LOADADDR=0x80800000

# This sets up the default configuration that we ship with
make tsimx6ul_defconfig

Once you have the configuration ready you can make your changes to the kernel. Commonly a reason for recompiling is to add support that was not built into the standard image's kernel. You can get a menu to browse available options by running:

make menuconfig

You can use the "/" key to search for specific terms through the kernel.

Build the kernel

Once you have it configured you can begin building the kernel. This usually takes about 5-10 minutes. This group of commands will also output a uImage file used by U-Boot on the TS-7680.

make && make zImage && make modules

We recommend running 'make' with the -jX argument, where X is the number of CPU cores+1 present on the build machine. This will greatly increase build speed.

Install the kernel/initramfs, headers, and modules

Next you need to install the kernel and modules to the SD card. Use the following to update the kernel, headers, and modules, this assumes the SD card connected to the workstation is assigned the device node /dev/sdc, please adjust the first command based on your specific setup:

export DEV=/dev/sdc1
sudo mkdir /mnt/sd
sudo mount "$DEV" /mnt/sd
sudo cp arch/arm/boot/zImage  /mnt/sd/boot/
sudo cp arch/arm/boot/dts/imx6*ts*.dtb /mnt/sd/boot/
INSTALL_MOD_PATH="/mnt/sd" sudo -E make modules_install 
sudo -E make headers_install INSTALL_HDR_PATH="/mnt/sd/usr"
sudo umount /mnt/sd/
sync


Linux 4.9.y

We provide an aftermarket image that includes a 4.9.y kernel that is intended to be used with Debian Stretch.

Compiling the kernel requires an armhf toolchain. We recommend development using Debian Stretch workstation which includes an armhf compiler in the repositories. See the Debian Stretch cross compile section for instructions on installing the proper cross compiler.

Additionally, some libraries and tools are required for the kernel build process:

# Install dependencies for kernel build
# The following command is for Ubuntu / Debian workstations. If using a different
# distribution, please consult distribution docs for the proper commands to install
# new packages/tools/libraries/etc.
apt-get install libncurses5-dev bc lzop


git clone https://github.com/embeddedTS/linux-4.9.y
cd linux-4.9.y

# These next commands set up some necessary environment variables
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export LOADADDR=0x80800000

# This sets up the default configuration that we ship with
make tsimx6ul_defconfig

## Make any changes in "make menuconfig" or driver modifications, then compile
make && make zImage


To install the kernel and modules to an SD card, attach it to the PC and assuming the the SD card shows up as /dev/sdc, run the following:

export DEV=/dev/sdc1
sudo mount "$DEV" /mnt/sd
sudo rm /mnt/sd/boot/zImage
sudo cp arch/arm/boot/zImage  /mnt/sd/boot/zImage
sudo cp arch/arm/boot/dts/imx6ul*ts*.dtb /mnt/sd/boot/
INSTALL_MOD_PATH="/mnt/sd" sudo -E make modules_install 
sudo -E make headers_install INSTALL_HDR_PATH="/mnt/sd/usr"
sudo umount /mnt/sd/
sync

Production Mechanism

The TS-7553-V2's U-Boot has the ability to locate and run a U-Boot script file named /tsinit.ub on the root of a USB drive. This process occurs when attempting to boot to the U-Boot shell. If this script exists, U-Boot will load and run it automatically. This is intended for the initial production of units and allows mass programming various media from a USB mass storage device.

The USB blasting image can be downloaded here. This includes a basic linux kernel and a small initramfs that will mount the USB drive at /mnt/usb/ and execute /mnt/usb/blast.sh.

The blast image and scripts require a minimum of 50 MB; this plus any disk images or tarballs used dictate the minimum disk size required. The USB drive must have at least 1 partition, with the first partition being formatted ext2/3 or fat32/vfat.

Note: The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.
# This assumes USB drive is /dev/sdc:
sudo mkfs.ext3 /dev/sdc1
sudo mkdir /mnt/usb/
sudo mount /dev/sdc1 /mnt/usb/
sudo tar --numeric-owner -xf /path/to/tsimx6ul_usb_blaster-latest.tar.bz2 -C /mnt/usb/

At this point, disk images or tarballs would be copied to the /mnt/usb/ folder and named as noted below. The latest disk images we provide can be downloaded from our FTP site, see the backup and restore section for links to these files. Note that the script expects images and tarballs to have specific names. When using an ext* filesystem, symlinks can be used.

The formatted USB drive boots into a small Buildroot initramfs environment with filesystem and partitioning tools installed. This can be used to format SD, eMMC, or other disks. The Buildroot environment starts up and calls /blast.sh on the USB device. By default this script is set up to look for a number of of specific files on the USB disk and write these to media on the host device. Upon completion of the script the green or red LEDs will blink to visually indicate a pass or fail of the script. This script can be used without modification to write images from USB with these filenames:

SD Card sdimage.tar.{bz2,xz} Tar of the filesystem. This will repartition the SD card to 1 ext4 partition and extract this tar to the filesystem. If present, a /md5sums.txt file will be checked and every file can be verified on the filesystem. This md5sums file is optional and can be omitted, but it must not be blank if present.
sdimage.dd.{bz2,xz} Disk image of the card. This will be written to the SD card block device directly. If present, a sdimage.dd.md5 file be used to verify the data written to the SD card against this checksum.
eMMC emmcimage.tar.{bz2,xz} Tar of the filesystem. This will repartition the eMMC to 1 ext4 partition and extract this tar to the filesystem. If present, a /md5sums.txt file will be checked and every file can be verified on the filesystem. This md5sums file is optional and can be omitted, but it must not be blank if present.
emmcimage.dd.{bz2,xz} Disk image of the card. This will be written to mmcblk1 directly. If present, a emmcimage.dd.md5 file be used to verify the data written to the SD card against this checksum.

Most users should be able to use the above script without modification. Our buildroot sources are available from our github repo. To build the whole setup and create a USB drive, the following commands can be used. See the repository README for information on the project and how to make modifications.

make tsimx6ul_usbprod_defconfig && make

The resulting output file tsimx6ul-usb-production-rootfs.tar.bz2 can be unpacked to the first partition of the USB drive as outlined above.

Features

Battery Backed RTC

The TS-7553-V2 implements a M41T00S STMicro Battery Backed RTC using an external and replaceable coin cell battery. This RTC is connected to the CPU via I2C and is handled by the kernel and is presented as a standard RTC device in linux.

Bluetooth

Note: The latest image for this platform as of April 28th, 2022 has known issues with the Wi-Fi driver and BLE coexistence due to incompatibility with cfg80211 powersave modes.

If using both Wi-Fi and BLE, it is strongly recommended to bring up the Wi-Fi interface, and then run iw wlan0 set power_save off to disable powersave modes.

This issue will be addressed in future images and has already been addressed in our kernel sources. We will continue to provide updates as we receive them from the Wi-Fi module manufacturer.


The Wi-Fi option for this platform also includes a Bluetooth 5.0 LE module. Support for Bluetooth is provided by the BlueZ project. BlueZ has support for many different profiles for HID, A2DP, and many more. Refer to the BlueZ documentation for more information. Please see our BLE Examples page for information on installing the latest BlueZ release, getting started, and using demo applications.

Both Wi-Fi and Bluetooth can be active at the same time on this platform. Note however, that either the Wi-Fi interface needs to be not brought up if Wi-Fi is unused, or it needs to actively connect to an access point or act as an access point. The Bluetooth module can be activated with the following commands:

For Bluez versions found on Debian Stretch and below:

# Enable Bluetooth, and load the firmware
echo BT_POWER_UP > /dev/wilc_bt
sleep 1
echo BT_DOWNLOAD_FW > /dev/wilc_bt
sleep 1

# Attach the BLE device to the system, increase the baud, and enable flow control
hciattach /dev/ttymxc2 any 115200 noflow
sleep 1
hcitool cmd 0x3F 0x0053 00 10 0E 00 01
stty -F /dev/ttymxc2 921600 crtscts

# Note that no other HCI commands should be used! In older versions of BlueZ, HCI commands exist alongside bluetoothd, however HCI commands can interfere with the bluetoothd stack.


For newer versions of BlueZ found on Debian Buster or newer, or newer versions of BlueZ built from source:

echo BT_POWER_UP > /dev/wilc_bt
sleep 1
echo BT_DOWNLOAD_FW > /dev/wilc_bt
sleep 1

btattach -N -B /dev/ttymxc2 -S 115200 &
sleep 1
bluetoothctl power on
sleep 1
hcitool cmd 0x3F 0x0053 00 10 0E 00 01
kill %1 # This terminates the above btattach command
sleep 1
btattach -B /dev/ttymxc2 -S 921600 &


At this point, the device is running at 921600 baud with flow control, and is fully set up ready to be controlled by various components of BlueZ tools. For example, to do a scan of nearby devices:

bluetoothctl
power on
scan on

This will return a list of devices such as:

root@ts-imx6ul:~# bluetoothctl  
Agent registered
[CHG] Controller F8:F0:05:XX:XX:XX Pairable: yes
[bluetooth]# power on
Changing power on succeeded
[CHG] Controller F8:F0:05:XX:XX:XX Powered: yes
[bluetooth]# scan on
Discovery started
[CHG] Controller F8:F0:05:XX:XX:XX Discovering: yes
[NEW] Device 51:DD:C0:XX:XX:XX Device_Name
[NEW] Device 2A:20:E2:XX:XX:XX Device_Name
[CHG] Device 51:DD:C0:XX:XX:XX RSSI: -93
[CHG] Device 51:DD:C0:XX:XX:XX RSSI: -82
[NEW] Device E2:08:B5:XX:XX:XX Device_Name
[CHG] Device 51:DD:C0:XX:XX:XX RSSI: -93
[CHG] Device 2A:20:E2:XX:XX:XX RSSI: -94
[NEW] Device 68:62:92:XX:XX:XX Device_Name
[NEW] Device 68:79:12:XX:XX:XX Device_Name
[bluetooth]# quit

Please note that the Bluetooth module requires the modem control lines CTS and RTS as flow control when running at higher baud rates. It is possible to run the module at the initial 115200 baud if the flow control lines are unwanted.

The module supports some other commands as well:

# Allow the BT chip to enter sleep mode
echo BT_FW_CHIP_ALLOW_SLEEP > /dev/wilc_bt

# Power down the BT radio when not in use
echo BT_POWER_DOWN > /dev/wilc_bt

CAN

Note: The TS-7553-V2 Rev. B PCB does not have software control of the CAN_EN# pin for the transceivers and they are always enabled. This is addressed in later hardware revisions.

The i.MX6UL CPU has two FlexCAN ports that use the linux SocketCAN implementation. The ports can be set up and used with the following commands:

ip link set can0 up type can bitrate 1000000
ip link set can1 up type can bitrate 1000000


The CAN transceivers are automatically controlled by the kernel. If either of the interfaces are brought up in linux then both transceivers will be enabled together. When both interfaces are brought down, then the transceivers will be disabled. By default when the kernel boots, the interfaces are down, and therefore the transceivers are disabled.

At this point the ports can be used with standard SocketCAN libraries. In Debian we provide the utilities 'cansend' and 'candump' to test the ports or as a simple packet send/receive tool. In order to test the two ports together, tie CAN_H of both CAN ports together, doing the same for the CAN_L pins. Then use the following commands:

candump can0 &
cansend can1 7Df#03010c
#This command will return
  can0  7DF  [3] 03010c


The above example packet is designed to work with the Ozen Elektronik myOByDic 1610 ECU simulator to read the RPM speed. In this case, the ECU simulator would return data from candump with:

 <0x7e8> [8] 04 41 0c 60 40 00 00 00 
 <0x7e9> [8] 04 41 0c 60 40 00 00 00 

In the output above, columns 6 and 7 are the current RPM value. This shows a simple way to prove out the communication before moving to another language.

The following example sends the same packet and parses the same response in C:

#include <stdio.h>
#include <pthread.h>
#include <net/if.h>
#include <string.h>
#include <unistd.h>
#include <net/if.h>
#include <sys/ioctl.h>
#include <assert.h>
#include <linux/can.h>
#include <linux/can/raw.h>

int main(void)
{
	int s;
	int nbytes;
	struct sockaddr_can addr;
	struct can_frame frame;
	struct ifreq ifr;
	struct iovec iov;
	struct msghdr msg;
	char ctrlmsg[CMSG_SPACE(sizeof(struct timeval)) + CMSG_SPACE(sizeof(__u32))];
	char *ifname = "can0";
 
	if((s = socket(PF_CAN, SOCK_RAW, CAN_RAW)) < 0) {
		perror("Error while opening socket");
		return -1;
	}
 
	strcpy(ifr.ifr_name, ifname);
	ioctl(s, SIOCGIFINDEX, &ifr);
	addr.can_family  = AF_CAN;
	addr.can_ifindex = ifr.ifr_ifindex;
 
	if(bind(s, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
		perror("socket");
		return -2;
	}
 
 	/* For the ozen myOByDic 1610 this requests the RPM guage */
	frame.can_id  = 0x7df;
	frame.can_dlc = 3;
	frame.data[0] = 3;
	frame.data[1] = 1;
	frame.data[2] = 0x0c;
 
	nbytes = write(s, &frame, sizeof(struct can_frame));
	if(nbytes < 0) {
		perror("write");
		return -3;
	}

	iov.iov_base = &frame;
	msg.msg_name = &addr;
	msg.msg_iov = &iov;
	msg.msg_iovlen = 1;
	msg.msg_control = &ctrlmsg;
	iov.iov_len = sizeof(frame);
	msg.msg_namelen = sizeof(struct sockaddr_can);
	msg.msg_controllen = sizeof(ctrlmsg);  
	msg.msg_flags = 0;

	do {
		nbytes = recvmsg(s, &msg, 0);
		if (nbytes < 0) {
			perror("read");
			return -4;
		}

		if (nbytes < (int)sizeof(struct can_frame)) {
			fprintf(stderr, "read: incomplete CAN frame\n");
		}
	} while(nbytes == 0);

	if(frame.data[0] == 0x4)
		printf("RPM at %d of 255\n", frame.data[3]);
 
	return 0;
}

See the Kernel's CAN documentation here. Other languages have bindings to access CAN such as Python, Java using JNI.

In production use of CAN we also recommend setting a restart-ms for each active CAN port.

ip link set can0 type can restart-ms 100

This allows the CAN bus to automatically recover in the event of a bus-off condition.

CPU

This device features the i.MX6UL 696MHz Cortex-A7 from NXP. For more information about the processor and its included peripherals, refer to the CPU manual.

DIO

The TS-7553-V2 offers DIO and a single Relay. The DIO exposed to various headers and terminals are controlled via the CPU. All DIOs are controlled via the kernel sysfs interface. See the kernel's documentation for more detail. All DIO are 3.3 V tolerant unless otherwise noted. All DIO pins have a pullup resistor to 3.3 V.

To interact with DIO pins through the sysfs interface, it first must be exported to userspace, for example, DIO 136 is the En. Relay pin:

echo "136" > /sys/class/gpio/export

If you receive a permission denied on a pin, that means it is claimed by another kernel driver. If the command is successful, there will be a /sys/class/gpio/gpio136/ directory. The relevant files in this directory are:

 direction - "out" or "in"
 value - write "1" or "0", or read "1" or "0" if direction is in
 edge - write with "rising", "falling", or "none"
# Set GPIO 136 high
echo "out" > /sys/class/gpio/gpio136/direction
echo "1" > /sys/class/gpio/gpio136/value
# Set GPIO 136 low
echo "0" > /sys/class/gpio/gpio136/value

# Read the value of GPIO 82, the Push Switch
echo "82" > /sys/class/gpio/export
echo "in" > /sys/class/gpio/gpio82/direction
cat /sys/class/gpio/gpio82/value
DIO Function Location
18 UART5 CTS CN9_8
19 UART5 RTS CN9_7
23 RS-232 Shutdown# N/A
40 XBee DTR CN5_9
41 XBee RTS CN5_16
46 XBee CTS CN5_12
75 NO Charge Jumper# NO Charge Jumper
81 SD Boot Jumper# SD Boot Jumper
82 Push Switch# Push Switch
83 U-Boot Jumper# U-Boot Jumper
84 XBee Reset# CN5_5
117 [1] Keypad 0 HD4_2
118 [1] Keypad 1 HD4_3
119 [1] Keypad 2 HD4_4
120 [1] Keypad 3 HD4_5
121 En. LCD Backlight N/A
128 Power Fail N/A
135 En. XBee USB# N/A
136 En. Relay N/A
  1. 1.0 1.1 1.2 1.3 Note that using this pin as standard DIO requires unloading the modules used by the Keypad.


As an output, the value file can be written to 0 for low (GND), or 1 for high (3.3V). As an input the GPIO pins have internal pullups. It is also possible to use any processor GPIO as an interrupt by writing the edge file, and then using select() or poll() on the value file for changes. Note that when the DIO is set as an output, the value file will always read back 0, regardless of actual output state.


Special DIO

The linux GPIO subsystem has a few shortcomings, specifically, an inability to set default output state from the kernel devicetree. Because of this, a number of DIO are implemented as LEDs in the kernel; pins that control various power supplies. While there is also a regulator subsystem that these could be used with, the regulator controls have their own issues as well. The LED subsystem is a very straightforward way to control IO pins in a similar manner to linux GPIO via the sysfs interface.

To enable a particular output, write a 1 to the brightness file for one of these special DIO. For example, to enable 4 V on the CN5 XBee Socket header:

echo 1 > /sys/class/leds/en-modem-5v/brightness


To disable any of the outputs, write a 0 to the brightness file. For example, to disable power to the USB host port:

echo 0 > /sys/class/leds/en-usb-5v/brightness


DIO Function Location
en-usb-5v Enable 5 V to USB host Internal and external USB host
en-modem-5v[1] Enable 4 V to CN5 XBee Socket CN5_1[2]
en-xbee-3v3[1] Enable 3.3 V to CN5 XBee Socket CN5_1[2]
en-emmc Enable power to the eMMC device N/A
  1. 1.0 1.1 Only one of these can be enabled at any time. If en-xbee-3v3 is enabled, en-modem-5v will be disabled in hardware to prevent damage.
  2. 2.0 2.1 CN5_6, VBUS, will also be affected by this enable. See the XBee Socket section for more information.

eMMC Interface

The i.MX6UL SD card controller supports the MMC specification, the TS-7553-V2 includes a soldered down eMMC IC to provide on-board flash media.

Our default software image contains 3 partitions:

Device Contents
/dev/mmcblk1 eMMC block device
/dev/mmcblk1boot0 eMMC boot partition
/dev/mmcblk1boot1 eMMC boot partition
/dev/mmcblk1p1 Full Debian linux partition


This platform includes an eMMC device, a soldered down MMC flash device. Our off the shelf builds are 4 GB, but up to 64 GB are available for customized builds. The eMMC flash appears to Linux as an SD card at /dev/mmcblk1. Our default programming of the eMMC is the same as the SD card image for standard partitions, but includes additional boot partitions that are used by U-Boot and are not affected by the eMMC partition table.

The eMMC module has a similar concern by default to SD cards in that they should not be powered down during a write/erase cycle. However, this eMMC module includes support for setting a fuse for a "Write Reliability" mode, and a "psuedo SLC (pSLC)" mode. With both of these enabled all writes will be atomic to 512 B and each NAND cell will be treated as a single layer rather than a multi-layer cell. If a sector is being written during a power loss, a block is guaranteed to have either the old or new data. Even in cases where the wrong data is present on the next boot, fsck is often able to deal with the older data being present in a 512 B block. The downsides to setting these modes are that it will reduce the overall write speed and halve the available space on the eMMC to roughly 1.759 GB. Please note that even with these settings, Technologic Systems strongly recommends designing the end application to eliminate any situations where a power-loss event can occur while any disk is mounted as read/write. The TS-SILO option for the TS-7553-V2 can help to eliminate the dangerous situation.

The "mmc-utils" package is used to enable these modes. The command is pre-installed on the latest image. Additionally we have created a script to safely enable the write reliability and pSLC modes. Since the U-Boot binary and environment reside on the eMMC, care must be taken to save the current state of the boot partitions, enable the modes, restore the boot partitions, and re-enable proper booting options. This script can be used in combination with the production mechanism scripting to complete these steps as part of an end application production process.


WARNING: Enabling these modes causes all data on the disk to become invalid and must be rewritten. Do not attempt to run the 'mmc' commands from the script individually, all steps in the script must occur as they are or the unit may be unable to boot. If there are any failures of the script, care must be taken to resolve any issues while the unit is still booted or it may fail to boot in the future.
WARNING: The script is only compatible with Rev. D or newer PCBs. Running the script on any previous PCB revision WILL result in the unit being unable to boot! There is no safe way to enable these modes on previous PCB revisions.
Note: Enabling these modes is a one-way operation, it is not possible to undo them once they are made. Because of this, setting these eMMC modes will invalidate Technologic Systems' return/replacement warranty on the unit. See the warranty section for more information on this.


The 'emmc_reliability' script can be found in the TS-7553-V2 utilities github repository.

The script must be run when boot from any media other than eMMC, such as SD, NFS, or USB. No partition of the eMMC disk can be mounted when these commands are run. Doing so may result in corruption or inability for the unit to boot. Once the pSLC mode is enabled, all data on the disk will become invalid. This means the partition table will need to be re-created, the filesystems formatted, and all filesystem contents re-written to disk. This is why we recommend using this script in conjunction with the production mechanism scripting. The 'emmc_reliability' script can be run first, then the rest of the production script can create and format the partitions as well as write data to disk.

The script requires a single argument, the device node of the eMMC disk, and will output verbosely to stderr. Any specific errors will also be printed out on stderr.

Example usage:

./emmc_reliability /dev/mmcblk1

Upon successful run, the script will return 0. Any errors will return a positive code. See the script for detailed error code information.

Ethernet Port

The NXP processor implements a 10/100 ethernet controller with support built into the Linux kernel. Standard Linux utilities such as ifconfig/ip can be used to control this interface. See the Configuring the Network section for more details. For the specifics of this interface see the CPU manual.

FRAM

The unit supports an optional non-volatile Ferroelectric RAM (FRAM) device. The Cypress FM25L16B is a 2kbyte device, in a configuration not unlike an SPI EEPROM. However, the nature of FRAM means it is non-voltile, incredibly fast to write, and is specified with a 100 trillion read/write cycles, with a 150 year data retention. The device is connected to linux, and presents itself as a flat file that can be read and written like any standard linux file.

The EEPROM file can be found at /sys/class/spi_master/spi2/spi2.2/eeprom

I2C

The i.MX6UL supports standard I2C at 100khz, or using fast mode for 400khz operation. The CPU has 3 I2C buses used on the TS-7553-V2.

I2C 1 is a bus for the RTC and the supervisory microcontroller. This bus is used with CPU GPIO pins rather than an internal SPI peripheral, this appears to linux as "/dev/i2c-0"

/dev/i2c-0
Address Device
0x2a Supervisory microcontroller
0x68 Battery backed RTC

The I2C 2 bus is connected to the Daughter Card header on HD1 and is meant as a general use device. This can be connected to any of our supported daughter cards or any customer designed daughter cards that may need I2C. There are no other connections on this I2C bus, so the entire address range is available for use. The I2C bus is implemented with the CPU I2C peripheral, this appears to linux as "/dev/i2c-2"

The I2C 3 bus is connected internally to the optional IMU (gyroscope/accelerometer/magnetometer). This bus is set up with CPU GPIO pins rather than an internal SPI peripheral, it appears to linux as "/dev/i2c-3"

/dev/i2c-3
Address Device
0x68 MPU-9250 IMU


It is also possible to connect additional I2C busses via GPIO pins if further interfaces are needed. See an example here.

The kernel makes the I2C available at /dev/i2c-# as noted above. Linux i2c-tools (i2cdetect, i2cget, i2cset) can be used to interface with devices, or custom clients can be written.

IMU

Note: As of commit 1382dfc550f733c81c56f3f4ed26a708cfa8662b in our github kernel repository, there is kernel support provided for the IMU. Using this is preferred over the userspace method below. The following section will be reworked if a new image is released using an updated kernel. Until then, if kernel support is desired, it is possible to compile the latest kernel to add this functionality.

Kernel support will create a number of files in "/sys/bus/iio/devices/iio:device0/" to access data from the IMU.

Magnetometer can be activated with the command 'echo ak8975 0x0c > /sys/bus/i2c/devices/i2c-4/new_device' and will be made available via a number of files in "/sys/bus/iio/devices/iio:device1/"


This platform can support an MPU-9250 IMU (Inertial Measurement Unit) device. This provides a MEMS (Microelectromechanical Systems) gyroscope, accelerometer, and magnetometer. The physical interface is over an I2C bus, and the controlling software is entirely userspace. This allows for easy integration in to applications and reduces overhead of kernel calls. Support for this MPU-9250 is provided through a project called BB-MPU9150. While it is targeted at the MPU-9150, the MPU-9250 used on this platform is a lower power variant.

The following commands can be used to download, build, install, calibrate, and run the application for the IMU:

Clone the repository:

git clone https://github.com/embeddedTS/bb_mpu9150
cd bb_mpu9150/src/linux-mpu9150/


Build the project:

DEFS="-DMPU9250" make

# If building via a cross compiler, it can be passed on the command line:
CROSS_COMPILE=arm-linux-gnueabihf- DEFS="-DMPU9250" make

# It is also possible to specify the default I2C bus on the command line:
DEFS="-DMPU9250 -DDEFAULT_I2C_BUS=<bus>" make

See the I2C section for a listing of the I2C buses.


Calibration has two steps, one for the accelerometer and one for the magnetometer. The output of the calibration is saved in the current directory. In order to properly calibrate the IMU the tool must be started, and while it is running, the whole physical device must be slowly rotated completely through every axis. Being slow is key as this process is measuring the effect of gravity on the device for minimum and maximum values. Rapid movements during this time will increase the forces applied and will throw off the calibration. Once all of the axes have been rotated through, press ctrl+c to end the calibration and write the calibration file to disk.

Note the the proper I2C bus number must be passed in order for the tool to communicate with the IMU. See the I2C section for a listing of the I2C buses. If the tool was built with the correct

./imucal -b<bus> -a  # To calibrate the accelerometer, must move slowly
./imucal -b<bus> -m  # To calibrate the magnetometer, can move faster

The calibration tool will output 'accelcal.txt' and 'magcal.txt'. If these files are in the same folder as the 'imu' binary then they will automatically be loaded when the binary is executed.


At this point, the 'imu' binary can be run to gather and display samples of the data. The readings below were taken from a unit sitting flat on a desk after calibration was complete:

./imu -b<bus>

Initializing IMU .......... done


Entering read loop (ctrl-c to exit)

X: 1 Y: 3 Z: 76

For further information on using this tool, the various modes of operation it supports, and developing applications that use it please see the documentation in the BB-MPU9150 project github.

Jumpers

The TS-7553-V2 has a set of jumpers located near the SuperCaps on the edge of the SBC. These jumpers control a number of aspects of the TS-7553-V2's behavior. The jumpers are labeled on the silkscreen rather than numbered:

Label Description
NO Charge When jumper is set, disable charging of the SuperCaps. Beneficial for early development and testing.
SD Boot When jumper is set, boot kernel and Debian from the SD card. Otherwise boot kernel and Debian from eMMC. This jumper influences U-Boot behavior.
U Boot When jumper is set, pause booting in U-Boot and drop to a U-Boot shell. Otherwise boot straight to Debian.
CAN When jumper is set, adds a 120 ohm termination resistor across CAN1 H and L pins. (Note: the CAN2 interface always has a 120 ohm termination)
485 When jumper is set, adds a 120 ohm termination resistor across RS-485 + and - pins.

LCD + Keypad

The TS-7553-V2 supports an optional 128x64 px. monochrome LCD and 4 membrane switches all mounted in an enclosure. The LCD uses a simple SPI interface and is set up with a kernel driver to be a simple framebuffer. Fairly complex graphics can be created on the screen through the use of graphical libraries such as Cairo. The keypad is a simple 4 button keypad that is attached to the system through GPIO with a driver that behaves like a keyboard input. We have created a helper application as well as tests/demos for the LCD and keypad functionality. The sources can be found in the TS-7553-V2 Utilities github. The binaries are included in the default image.

The backlight can be controlled through a DIO pin and is automatically turned on when the helper application is started.

LCD

In order for the LCD to run, there is a module that must first be loaded, ts-st7565p-fb. On the TS-7553-V2, this module is auto-loaded by systemd, it's specified in /etc/modules-load.d/lcd_keypad.conf

The 128x64 px. monochrome LCD is connected to the system via SPI and uses a userspace application to format the data, and a driver to send it to the device. The LCD can be used as a generic framebuffer with this setup. The userspace application and driver are included by default, but must be manually run to set up.

/usr/local/bin/lcd-helper

Note that its possible with systemd to set this up to auto run on startup, followed by the application that would utilize the screen. This application should start up after all of the necessary modules have been loaded and the helper application has been started.


Two example binaries are also included in order to demonstrate the LCD's capabilities.

/usr/local/bin/cairo-test

Is a simple Cairo demonstration that draws a box, a line, a circle, and some text on to the display.


/usr/local/bin/bounce-test

Will display a bouncing box on the screen.

See the sources for more information on these demos and how they operate.

Keypad

In order for the membrane switches to run properly, there are two modules that must be loaded, gpio_keys, and matrix_keymap. On the TS-7553-V2, these modules are auto-loaded by systemd, these are specified in /etc/modules-load.d/lcd_keypad.conf

The 4 button membrane keypad allows for a 4 button input. These are set up on GPIO pins, and are connected to the system as a standard input event device. The four buttons are connected as arrow keys. An example binary is included in order to demonstrate the input capabilities of these buttons:

/usr/local/bin/keypad-test

Will draw a box around the screen with some text. When a button is pressed, it will display a block on the LCD above the button that has been pressed. Please note that the LCD device must first be set up and operational before this binary will launch.

See the sources in github for more information on this demo and how it operates.

LEDs

On all of our SBCs we include 2 indicator LEDs which are under software control. They can be manipulated from userspace using the LED sysfs interface. The LEDs have 4 behaviors from default software.

Green Behavior Red behavior Meaning
Solid On Off The kernel has booted and the system is running.
Off Solid On The unit has powered on and is in the bootloader.
On for 10s, off for 100ms, and repeating On for 10s, off for 100ms, and repeating The watchdog is continuously resetting the board. This happens when the system cannot find a valid boot device, or the watchdog is otherwise not being fed. This is normally fed by the kernel once a valid boot media has started. See the Watchdog Timer section for more details.
Off Off The device is unable to boot. Typically either it is not being supplied with enough voltage, or the unit has been otherwise damaged. If a stable voltage is being provided and the supply is capable of providing at least 1A to the unit, an RMA is suggested.
Off Blinking about 5ms on, about 10ms off. The device is receiving too little power, or something is drawing too much current from the unit's power rails causing the unit to reboot consistently.


The red and green LEDs can be controlled from userspace after bootup using the sysfs LED interface. For example, to turn on the red LED:

echo 1 > /sys/class/leds/red-led/brightness


A number of triggers are also available, including timers, disk activity, and heartbeat. These allow the LEDs to represent various system activities as they occur. See the kernel LED documentation for more information on triggers and general use of LED class devices.

We also use the LED control system to control a number of DIO pins which need to have their default state specified. See the DIO section for more information on this.

MicroSD Card Interface

The i.MX6ul SD card controller is used for the SD card present on the board which supports the SD and SDHC specifications. This controller has been tested with Sandisk Extreme SD cards which allow read speeds up to 20.5MB/s, and write speeds up to 21.5MB/s.

Our default software image contains a single partition:

Device Contents
/dev/mmcblk0 SD Card block device
/dev/mmcblk0p1 Full Debian linux partition

Reboot Source

The supervisory microcontroller is capable of saving and displaying the reason for the most recent reboot. This can be used to detect various errors that may occur in the field, as well as simple accounting of events. The source can be queried with tsmicroctl:

tsmicroctl -i

reboot_source=poweron


Possible sources and causes are:

Source Possible causes
poweron Power removed, Super Caps discharged, and then power applied
brownout[1] Like "poweron," however the SuperCaps have not fully discharged.
WDT WDT timeout; reboot command (which reboots via WDT)
sleep The system has woken up from a sleep command
  1. This situation is rare due to how the microcontroller handles TS-SILO. A loss of external power with safe shutdown will result in a "WDT" event.

Relay

The TS-7553-V2 has one SPDT relay rated for 5 A at 277 VAC or 30 VDC that can be toggled through a DIO pin. The PCH-105D2H relay closes in 10ms, and opens in 5ms. A very safe assumption would be that it will switch after 20ms. The common, NO (Normally Open), and NC (Normally Closed) connections are brought out on the screw terminal pin header. See the DIO section of the manual for information on manipulating the relays.

Contact Location
COM P1_7
NC P1_8
NO P1_6

Sleep

Note: As soon as the sleep command is issued the unit will go to sleep. If the proper precautions are not taken, filesystem corruption can result as the sleep mode removes all power from the CPU and other peripherals on the SBC


The addition of a microcontroller on board this SBC allows it to play a supervisory role over the CPU.

Low power sleep mode will remove power from all of the rails, turning off the CPU and every other peripheral save for the microcontroller. This mode offers extreme power savings, only requiring around 200 mW of power, with the ability to wake up after an arbitrary timeout (up to 1847297s, which is 21d 9h 8m 17s) with a 1s resolution. In order to enter this mode, issue the following command:

tsmicroctl --sleep <time in seconds>

Upon wake up, the system will do a normal bootup.

SPI

The i.MX6UL CPU has a native SPI peripheral that is used in a number of places on the TS-7553-V2. Additionally, kernel spidev support is added to allow SPI access from userspace. User SPI can be used for LCD access, a generic SPI connection on HD1, as well as user accessible FRAM.

The ECSPI peripheral in the i.MX6UL CPU is highly flexible and can even support SPI slave mode. For more information on the peripheral itself, please see the CPU reference manual.


The SPI peripheral is accessible as /dev/spidev2.x, where x is one of the three chip select lines. Additional chip select lines can be implemented if needed by adding them to the kernel device-tree by using GPIO.

CS Device
0 LCD CS
1 HD1
2 FRAM

See the kernel spidev documentation for more information on interfacing with the SPI peripherals.

SuperCaps

The TS-7553-V2 has an option to add two 2.7 V 25 F supercapacitors. The TS-SILO option can provide up to 65 seconds of power hold time automatically if the external power input is removed. The Power Fail input signal (see the DIO Section) can be used to determine if the exterior power has been removed or fallen below a valid input level. Using this signal, a proper shutdown can be issued to ensure that all data is flushed from cache to disk, and all disks are unmounted properly.

The supercapacitor's charge and discharge cycles are managed transparently by the supervisory microcontroller. A jumper is provided to disable the charging and use of the supercapacitors. This mode is very useful for development to allow for proper power-off conditions without having to wait for the supercapacitors to discharge. The supervisory microcontroller will also not allow the TS-7553-V2 to boot if power input is not valid. This means that if the system reboots safely due to a power failure, it will remain in a powered off state until external power is re-applied, or the supercapacitors discharge below the sustainable threshold.

By default, a script is started with systemd to monitor the Power Fail pin which will present all logged in users with a message saying that the power has failed and a graceful shutdown is taking place if the power input has failed. This script is located at /usr/local/bin/tssilomon

U-Boot is responsible for checking the "No Charge" jumper, if it is not populated then it will issue the charge command to the microcontroller. At this point the charging and topping off is completely handled by the supervisory microcontroller.

Additionally, U-Boot can delay booting until the supercapacitors are charged to a certain percentage, and optionally print the current percentage once per second. These are controlled with the environment variables "chrg_pct" and "chrg_verb" By setting chrg_pct to anything other than 0 (0 means do not wait, which is the default behavior), booting will be delayed until that percentage is reached. Setting chrg_verb to 1 will enable the verbose printing of the current percentage every second. Note that the supercapacitors may be at "0%" for a large period of time. The "0%" charge level is any charge level that is unable to sustain the TS-7553-V2 if power is removed. See the U-Boot section for information on setting environment variables.

A recommended value for using chrg_pct is 60%. This value was chosen because it can ensure the system is powered long enough to boot up and safely shut down (and provide an additional 8 s of power) if power is immediately cut once booting has started. Please note that this only applies to the default stock image, any further changes to the TS-7553-V2 hardware or software, such as connecting powered devices like USB mass storage or adding additional applications may cause the recommended value to not sustain the TS-7553-V2 until a safe shutdown is completed. The time it takes to reach 60% charge will vary depending on the present charge of the supercapacitors. On average, it will take about 20 seconds to charge the supercapacitors to 100%; this is assuming the supercapacitors have very recently fallen below the threshold voltage to sustain the TS-7553-V2, and that the unit is powered with a 12 V input. Note that at 5 V input the charge current is much lower in order to reduce strain on the power supply. This has the side effect of having an increased charge time compared to 12 V input.

The graph below highlights typical charge and discharge cycles.

Ts7553v2-silo.png

The green line represents seconds vs charge voltage of the supercapacitors with a 12 V input. The red line is the minimum charge voltage of the supercapacitors to sustain operation of the TS-7553-V2. The blue line represents the supercapacitor charge level during an external power failure while the CPU is idling with no ethernet connection. The orange line represents supercapacitor charge level during an external power failure with the CPU fully under load, constant network activity, and the relay coil energized.

UARTs

The TS-7553-V2 CPU offers 8 UARTs. The table below lists the CPU UARTs with their pin locations.

Num. Dev. Name Type TX / + Loc. RX / - Loc. RTS Loc. CTS Loc.
0 ttymxc0 USB Console N/A N/A N/A N/A
1 ttymxc1 RS-485 CN9_1 / P1_3 / HD2_1 CN9_6 / P1_4 / HD2_6 N/A N/A
2 ttymxc2 Bluetooth N/A N/A N/A N/A
3 ttymxc3 RS-232[1] HD2_3 HD2_2 N/A N/A
4 ttymxc4 RS-232[1] HD2_7 HD2_8 N/A N/A
5 ttymxc5 RS-232[1] CN9_3 CN9_2 CN9_7[2][3] CN9_8[2][4]
6 ttymxc6 TTL HD1_12 HD1_10[5] N/A N/A
7 ttymxc7 XBee/TTL CN5_3 CN5_2 N/A N/A
  1. 1.0 1.1 1.2 RS-232 transceiver can be shut down to reduce power. See the DIO section.
  2. 2.0 2.1 Signal implemented as GPIO.
  3. Output only
  4. Input only
  5. 5 V tolerant input

RS-485

The TS-7553-V2 has a single RS-485 port that supports automatic TXEN via kernel driver features and a GPIO pin. The RS-485 kernel support allows for tuning of timing, as well as polarity of the TXEN signal. For full information on using this feature, see the RS-485 kernel documentation. See the UARTs section for the location of the RS-485 port.

USB

The TS-7553-V2 offers multiple USB 2.0 host ports as well as OTG compatible ports. An on-board USB hub breaks out the host ports to multiple places, allowing the use of various devices. There is a single external USB A port, and a single internal USB A port. The internal port is provided by a USB A jack that is mounted in such a way to lay the connected USB dongle over the PCB, allowing most dongles to be contained within the TS-7553-V2 enclosure without issue.

The TS-7553-V2 has a single exposed USB B female device socket. By default, this USB device is the USB serial interface as provided by the supervisory microcontroller; however it is possible to route this USB interface to the CPU USB OTG port and enable USB gadget usage.

Power to the USB internal and external host ports can be controlled with the LED subsystem under the LED device: /sys/class/leds/en-usb-5v/ By writing to the "brightness" file in that folder a value greater than 0, it will enable USB power, setting it to 0 will turn it off. See the DIO section of the manual for more information on this.

USB Gadget

The USB B female jack by default provides a USB serial console via the supervisory microcontroller. The TS-7553-V2 provides an internal USB mux IC that can be switched to connect the CPU USB OTG port to the USB B female jack. Once booted, the kernel can support USB gadgets allowing the unit to emulate a number of various USB devices. Below is an example to set up the USB ethernet gadget:

First, load the gadget drivers and bring the interface up:

modprobe g_ether
ifconfig usb0 192.168.0.1 up

Next, switch the USB mux so that the USB device port now connects to the CPU OTG port. Note that when this command is run, USB serial will disconnect:

echo 71 > /sys/class/gpio/export
echo high > /sys/class/gpio/gpio71/direction

At this point the TS-7553-V2 will appear to the host system as a USB ethernet device, the TS-7553-V2 will have an IP of 192.168.0.1 on the USB interface. The host PC can set an IP address in this same subnet and will be able to communicate with the TS-7553-V2. See the linux USB gadget documentation for more information on the full set of devices that are available.

The default kernel is built with most USB gadgets built as modules. If any additional support is required, the kernel will need to be rebuilt with the options enabled.

Watchdog

The TS-7553-V2 implements a WDT inside the supervisory microcontroller. A standard kernel WDT driver is in place that feeds the WDT via the I2C bus. As soon as the kernel starts it will start the WDT and feed it on 30 second timeouts every 15 seconds. If a userspace application opens and uses the watchdog file the kernel will stop auto-feeding and the user application is now responsible for feeding the WDT. The kernel driver supports the "Magic Close" feature of the WDT. This means that a 'V' character must be fed in to the watchdog file before the file is closed in order to disable the WDT. If this does not happen then the WDT is not stopped and it will continue it's countdown. Additionally, if the kernel is compiled with CONFIG_WATCHDOG_NOWAYOUT then the WDT can never be stopped once it is started at boot.

See the Linux WDT API documentation for more information.

WIFI

This board uses an ATWILC3000-MR110CA IEEE 802.11 b/g/n Link Controller Module With Integrated Bluetooth® 4.0. Linux provides support for this module using the wilc3000 driver.

Summary features:

  • IEEE 802.11 b/g/n RF/PHY/MAC SOC
  • IEEE 802.11 b/g/n (1x1) for up to 72 Mbps PHY rate
  • Single spatial stream in 2.4GHz ISM band
  • Integrated PA and T/R Switch Integrated Chip Antenna
  • Superior Sensitivity and Range via advanced PHY signal processing
  • Advanced Equalization and Channel Estimation
  • Advanced Carrier and Timing Synchronization
  • Wi-Fi Direct and Soft-AP support
  • Supports IEEE 802.11 WEP, WPA, and WPA2 Security
  • Supports China WAPI security
  • Operating temperature range of -40°C to +85°C

Specifications

Power Specifications

The TS-7553-V2 accepts a range of voltages from 5 V to 28 V DC. Note that there is a dead zone around 5.4 V as this is the transition point from directly accepting 5 V input to changing over to the switching regulator that can accept up to 28 V. The full voltage range is accepted on the same set of power input pins.

Input Min voltage Max voltage
5 V input range 4.7 5.3
28 V input range 5.6 28

Power Consumption

Power consumption of the TS-7553-V2 can vary greatly depending on the build options, the peripherals in use, and the end application behavior. The majority of the power savings are in the automatic CPU scaling and by disabling the Ethernet PHY. Additionally, direct 5 V input is more efficient than using a higher input voltage. This is due to the fact that any input voltage above 5 V is first run through an on-board switching regulator in order to regulate it down to 5 V.

The following tests were performed on a TS-7553-V2 Rev. D PCB. When the measurements were taken the USB serial console was disconnected first to ensure the most accurate measurement possible and the TS-SILO supercapacitors were not charging during the testing. The exact model used for testing is TS-7553-V2-SMW5I.

TS-7553-V2-SMW5I
Test Input V Average W
CPU idle, eth0 brought down, booted from eMMC with no SD card, CAN disabled 5 0.7
CPU idle, eth0 linked, booted from SD, CAN disabled 5 1
CPU running openssl speed, eth0 linked running iperf, booted from SD, CAN enabled 5 1.45
CPU idle, eth0 brought down, booted from eMMC with no SD card, CAN disabled 12 0.93
CPU idle, eth0 linked, booted from SD, CAN disabled 12 1.23
CPU running openssl speed, eth0 linked running iperf, booted from SD, CAN enabled 12 1.66

TS-SILO SuperCaps

Charging of the supercapacitors causes a change in overall power consumption of the whole system. Because of this, the numbers below are the average curve and peak power draw during a full charge cycle of the TS-SILO technology itself. In other words, the power noted below is separate from the numbers listed above and should be added to the numbers above to sum the total power draw of the whole device.

The current consumption of TS-SILO supercapacitors is not linear during charging. The charge process has a curve to it and the maximum average current consumption is near 80% of full capacity. Below we document the minimum and maximum average over the whole curve and the peak consumption that could be seen.

TS-SILO charging
Charging V Min Avg. W Max Avg. W Peak W
5 0.85 1 1.45
12 2.7 5.3 6.3

External Interfaces

HD1 Pin Header

Pin Name
HD1_1 VIN
HD1_2 POE_78
HD1_3 GND
HD1_4 POE_45
HD1_5 GND
HD1_6 POE_TX
HD1_7 SPI_CS# 1
HD1_8 POE_RX
HD1_9 I2C_DAT
HD1_10 UART6 RXD [1]
HD1_11 USB Host -
HD1_12 UART6 TXD
HD1_13 USB Host +
HD1_14 I2C_CLK
HD1_15 5 V
HD1_16 5 V
HD1_17 SPI_MISO
HD1_18 SPI_MOSI
HD1_19 3.3 V
HD1_20 SPI_CLK
Pin Layout
1 2
3 4
5 6
7 8
9 10
11 12
13 14
15 16
17 18
19 20
  1. 5V tolerant input

HD2 COM2 Header

10pin com header.png

Pin Name
HD2_1 UART1 RS-485 +
HD2_2 UART3 RXD
HD2_3 UART3 TXD
HD2_4 CAN1_H
HD2_5 GND
HD2_6 UART1 RS-485 -
HD2_7 UART4 TXD
HD2_8 UART4 RXD
HD2_9 CAN1_L
HD2_10 NC


HD4 Keypad Interface

Pin Name
HD4_1 GND
HD4_2 Keypad 0 / DIO 117 [1]
HD4_3 Keypad 1 / DIO 118 [1]
HD4_4 Keypad 2 / DIO 119 [1]
HD4_5 Keypad 3 / DIO 120 [1]
HD4_6 GND
  1. 1.0 1.1 1.2 1.3 Note that using this pin as standard DIO requires unloading the modules used by the Keypad.

CN5 XBee Socket

The XBee socket on the TS-7553-V2 is designed to support multiple devices. In addition to the standard range of XBee products from Digi, it also supports NibeLink Skywire cellular modem modules. The TS-7553-V2 can provide 3.3 V or 4 V to the power pin of the XBee form factor, and can also support USB devices provided by compatible modules.

Power is not turned on by default and must be explicitly enabled. The 3.3 V or 5 V regulators can be enabled by manipulating the regulator enable DIO.

USB on pins 7 and 8 of the XBee socket are by default disconnected from module. This is because some older modules call out these pins with different functions or to leave as a no connect. A DIO is used to enable the USB host connection to the XBee socket. See the DIO section of the manual for more information.

The special VBUS output on pin 6 can provide different voltages based on the combination of 3.3 V and the 5 V regulator enables. VBUS is 0 V output when neither of the regulators are enabled and when only the "XBee 3.3 V" supply is enabled. VBUS is ~4.7 V output when only the "MODEM 5 V" regulator is enabled. And VBUS is 3.3 V then both "XBee 3.3 V" and "MODEM 5 V" regulators are enabled. Note that in the last case, VCC to the XBee socket will still remain at 3.3 V, and the actual 5 V regulator is disabled for safety.

Some form factor compatible modules provide a USB device on two pins of the XBee socket. In order to ensure compatibility with most modules, these USB pins are electrically disconnected by default and must be enabled. In order to enable USB on the XBee socket, assert the En. XBee USB# signal. Note that most XBee modules will not function if USB is enabled. Only enable the USB connectivity if the module used supports USB on pins 7 and 8!


This example sets up a Nimbelink Cellular modem on the XBEE header.

WARNING: This should not be done with 3.3V XBEE modules
# Enable USB to the XBEE header:
echo 135 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio135/direction 

# Turn off XBEE 3.3V
echo 0 > /sys/class/leds/en-xbee-3v3/brightness

# Enable modem 4V:
echo 1 > /sys/class/leds/en-modem-5v/brightness

# Set XBEE_RESET# high to take it out of reset:
echo 84 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio84/direction
sleep 1
echo high > /sys/class/gpio/gpio84/direction

# After this is run it requires about 20-25 seconds before its USB device appear to the system

This examples turns on an XBEE and removes it from reset:

# Turn off modem 4V:
echo 0 > /sys/class/leds/en-modem-5v/brightness

# Turn on XBEE 3.3V
echo 1 > /sys/class/leds/en-xbee-3v3/brightness

# Set XBEE_RESET# high to take it out of reset:
echo 84 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio84/direction
sleep 1
echo high > /sys/class/gpio/gpio84/direction
Pin Name
CN5_1 VCC [1]
CN5_2 UART7 RXD
CN5_3 UART7 TXD
CN5_4 GND
CN5_5 XBee reset# / DIO 84
CN5_6 VBUS
CN5_7 USB Host + [2]
CN5_8 USB Host - [2]
CN5_9 DIO 40
CN5_10 GND
CN5_11 GND
CN5_12 DIO 46
CN5_13 NC
CN5_14 3.3 V
CN5_15 GND
CN5_16 DIO 41
CN5_17 NC
CN5_18 NC
CN5_19 NC
CN5_20 GND
Zigbee Header
  1. This pin will provide 3.3 V or 4 V depending on if "XBee 3.3 V" or "MODEM 5 V" is enabled. See the DIO section for more information.
  2. 2.0 2.1 Enabled with En. XBee USB#.

P1 Pin Header

Pin Name
1 Power-in VCC
2 Power-in VSS
3 UART1 RS-485 +
4 UART1 RS-485 -
5 GND
6 Relay NO
7 Relay COM
8 Relay NC

CN9 DB-9 Header

DB9.svg

Pin Name
1 UART1 RS-485 +
2 UART5 RXD
3 UART5 TXD
4 CAN0_H
5 GND
6 UART1 RS-485 -
7 UART5 RTS[1]
8 UART5 CTS[2]
9 CAN0_L
10 GND
  1. Output only
  2. Input only

Revisions and Changes

Microcontroller Changelog

Revision Changes
0xF Resolved issue with microcontroller going to sleep in situations where it would receive a USB suspend packet

PCB Revisions

Revision Changes
B Initial Engineering Sampling release
C
  • Add IMU
  • Connect CAN enable to DIO
  • eMMC power control
  • Bluetooth CTS/RTS swapped to correct pins
  • Add SPI FRAM
  • Add Ground on keypad pin header in correct location
D
  • Initial Production release
  • IMU moved due to I2C conflict
  • XBee USB electrical connection switchable for compatibility
  • Reduce 3.3 V line ripple
  • Reduce TS-SILO supercapacitor charge current
  • Reduce 5 V regulator audible output
  • Add FET to eMMC power control, inverts polarity

Software Images

Stock Images

Revision Changes
ts7553-V2-B-feb102017-prelim.tar.bz2 Initial image compatible with the Rev B PCB
ts7553-V2-B-mar162017-prelim.tar.bz2
  • Add support for auto-TXEN for RS-485
  • Add support for Atmel WiFi/Bluetooth module
ts7553-V2-B-may012017-prelim.tar.bz2
  • Use microcontroller WDT, add driver support
  • Enabled firmware download to support Bluetooth
  • Support SD card polling
  • Add support for the LCD and keypad option
ts7553-V2-B-jul202017-prelim.tar.bz2
  • Add support to Rev. C PCB
  • Added option to RS-485 driver to be able to support auto-TXEN at boot time
  • Fixups to wilc3000 WiFi driver
  • Reversed keypad pinmap since cable roll no longer necessary on Rev. C
  • Add support for SPI FRAM
ts7553-V2-oct182017-prelim.tar.bz2
  • Cleaner probe and failure of Atmel WiFi drivers
  • Added "low_latency" option to UART driver
  • Added CAN enable control as an LED
  • Pulled in mainline patch for FlexCAN FIFO RX overruns
ts7553-V2-dec152017.tar.bz2
  • Initial production release
  • Support for Rev. D PCB
  • Created I2C GPIO port for new IMU location on Rev. D PCB
  • Build in i2c-gpio support in to kernel
  • Moved I2C1 from CPU peripheral to GPIO due to BUG with halt/reset being controlled by this port
  • Set up eMMC power control as LED
  • Add ethernet PHY regulator control
  • CAN enabled moved to regulator control, automatic enable
  • Separate DTS for both Rev. C and Rev. D PCBs, needed to support different eMMC power control
  • Clean up of DTS

Linux 4.9.y Images

Revision Changes
ts7553-V2-linux4.9-20190402.tar.bz2 Initial release of 4.9 image. Includes Debian Stretch and Linux kernel 4.9.166

U-Boot

Revision Changes
February 16, 2017 Initial release for PCB Rev. B
April 5, 2017
  • Set up control of TS-SILO supercapacitor charging
  • Add support for wait_chrg delay
  • Added reset switch to break U-Boot booting
  • Added LED use
April 24, 2017
  • Set up USB hub oscillator and unreset at startup
  • Added initial POST test
October 16, 2017
  • Added destructive option to POST test
  • Enabled "ums" command to provide USB device functionality
  • Update NFS boot to match other products
  • Added Atmel WiFi module test to POST
  • Added FRAM test to POST
  • Set TS-SILO to only attempt to charge on compatible units
  • Tuned DDR3 timing based on NXP tuning tool
  • Cleanup of output
December 15, 2017
  • Initial production release
  • Add support for Rev. D PCB as well as Rev. C
  • Support for different eMMC sizes
January 15, 2018
  • Set USB 5 V power enable early in U-Boot for USB production

Product Change Notices

New eMMC chip

Due to an EOL on the older Micron MTFC4GMDEA-4M IT part, the replacement Micron MTFC4GACAJCN-4M IT has been qualified for use on this board. This new eMMC flash includes write reliability enabled by default. This will improve reliability for power loss events without requiring user intervention.

This updated part also has a larger erase block size which will require an updated production processes for those using the "emmc_reliability" script. This new chipset will require the latest version including this patch to function correctly.

Product Notes

FCC Advisory

This equipment generates, uses, and can radiate radio frequency energy and if not installed and used properly (that is, in strict accordance with the manufacturer's instructions), may cause interference to radio and television reception. It has been type tested and found to comply with the limits for a Class A digital device in accordance with the specifications in Part 15 of FCC Rules, which are designed to provide reasonable protection against such interference when operated in a commercial environment. Operation of this equipment in a residential area is likely to cause interference, in which case the owner will be required to correct the interference at his own expense.

If this equipment does cause interference, which can be determined by turning the unit on and off, the user is encouraged to try the following measures to correct the interference:

Reorient the receiving antenna. Relocate the unit with respect to the receiver. Plug the unit into a different outlet so that the unit and receiver are on different branch circuits. Ensure that mounting screws and connector attachment screws are tightly secured. Ensure that good quality, shielded, and grounded cables are used for all data communications. If necessary, the user should consult the dealer or an experienced radio/television technician for additional suggestions. The following booklets prepared by the Federal Communications Commission (FCC) may also prove helpful:

How to Identify and Resolve Radio-TV Interference Problems (Stock No. 004-000-000345-4) Interface Handbook (Stock No. 004-000-004505-7) These booklets may be purchased from the Superintendent of Documents, U.S. Government Printing Office, Washington, DC 20402.

Limited Warranty

See our Terms and Conditions for more details.

WARNING: Writing ANY of the CPU's One-Time Programmable registers will immediately void ALL of our return policies and replacement warranties. This includes but is not limited to: the 45-day full money back evaluation period; any returns outside of the 45-day evaluation period; warranty returns within the 1 year warranty period that would require SBC replacement. Our 1 year limited warranty still applies, however it is at our discretion to decide if the SBC can be repaired, no warranty replacements will be provided if the OTP registers have been written.


WARNING: Setting any of the eMMC's write-once registers (e.g. enabling enhanced area and/or write reliability) will immediately void ALL of our return policies and replacement warranties. This includes but is not limited to: the 45-day full money back evaluation period; any returns outside of the 45-day evaluation period; warranty returns within the 1 year warranty period that would require SBC replacement. Our 1 year limited warranty still applies, however it is at our discretion to decide if the SBC can be repaired, no warranty replacements will be provided if the OTP registers have been written.