From Technologic Systems Manuals
Jump to: navigation, search
TS-7400-V2
ts-7400-v2.gif
Product Page
Product Images
Specifications
Documentation
Schematic
Mechanical Drawing
FTP Path
Processor
Freescale i.MX286
454MHz ARMv5TE ARM926EJ-S
CPU Datasheet

Contents

1 Overview

The TS-7400-V2 was released October, 2013. This is a small embedded board with a Freescale i.MX286 454Mhz ARM9 CPU with 128-256MB DDR2.

2 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 boards run Debian and if you have no other distribution preference this is what we recommend.

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.

2.1 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-7400-V2 has an input voltage requirement of 5V DC through the main power barrel connector (center positive) or to the 5V pins on the expansion header. The TS-7400-V2 will require approximately 0.95W at idle. An ideal power supply for the TS-7400-V2 will allow up to 5W. There is an optional 8-28V DC regulated power input available that arrives at the rear of the SBC at silkscreen location CN5, with the negative lead situated nearest the long edge of the PCB.

Once you have applied power you should look for console output. The first output is from the bootrom:

HTLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLFLC              
>> TS-BOOTROM - built Oct 31 2013 22:13:45                                               
>> Copyright (c) 2013, Technologic Systems                                               
LLCLLLLLLLFLCLLJUncompressing Linux... done, booting the kernel.                         
Booted in 3.89s                                                                          
Initramfs Web Interface: http://ts7400-4f3029.local                                        
#       

The i.MX28 internal bootrom prints out the strings of letters to indicate various stages of its internal process. The TS-BOOTROM build date reflects when then imx-bootlets were built. When building a custom kernel from source this date will be changed and may not always reflect the kernel build date.

2.2 Get a Console

2.2.1 Option 1: Telnet

If your system is configured with zeroconf support (Avahi, Bonjour, etc) you can simply connect with:

telnet ts7400-<last 6 characters of the MAC address>.local
# You will need to use your TS-7400 MAC address, but 
# for example if you mac is 00:d0:69:01:02:03
telnet ts7400-010203.local

When the board first powers up it has two network interfaces. The first interface eth0 is configured to use IPv4LL, and eth0 is configured to use DHCP. The board broadcasts using multicast DNS advertising the _telnet._tcp service. You can use this to query all of the available TS-7400_V2s on the network.

From Linux you can use the avahi commands to query for all telnet devices with:

avahi-browse _telnet._tcp

Which would return:

+   eth0 IPv4 TS-7400 console [4f47a5]                      Telnet Remote Terminal local
+   eth0 IPv4 TS-7400 console [4f471a]                      Telnet Remote Terminal local

This will show you the mac address you can use to resolve the board. In this case you can connect to either ts7400-4f47a5.local or ts7400-4f471a.local



From Windows you can use Bonjour Print Services to get the dns-sd command. OSX also comes preinstalled with the same command. Once this is installed you can run:

dns-sd -B _telnet._tcp

Which will return:

Browsing for _telnet._tcp
Timestamp     A/R Flags if Domain                    Service Type              Instance Name
10:27:57.078  Add     3  2 local.                    _telnet._tcp.             TS-7400 console [4f47a5]
10:27:57.423  Add     3  2 local.                    _telnet._tcp.             TS-7400 console [4f471a]

This will show you the mac address you can use to resolve the board. In this case you can connect to either ts7400-4f47a5.local or ts7400-4f471a.local

2.2.2 Option 2: Serial Console

Console from Linux

There are many serial terminal applications for Linux, but 3 common implementations would be picocom, screen, and minicom. These examples assume that your COM device is /dev/ttyUSB0 (common for USB adapters), but replace them with the COM device on your workstation.

Linux has a few applications capable of connecting to the board over serial. You can use any of these clients that may be installed or available in your workstation's package manager:

Picocom is a very small and simple client.

picocom -b 115200 /dev/ttyUSB0

Screen is a terminal multiplexer which happens to have serial support.

screen /dev/ttyUSB0 115200

Or a very commonly used client is minicom which is quite powerful:

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.

Device Manager Putty Configuration

2.3 Initramfs

When the board first boots up you should have a console such as:

HTLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLFLC              
>> TS-BOOTROM - built Sep  4 2013 14:49:24                                               
>> Copyright (c) 2013, Technologic Systems                                               
LLCLLLLLLLFLCLLJUncompressing Linux... done, booting the kernel.                         
Booted in 3.89s                                                                          
Initramfs Web Interface: http://ts7600-4f3029.local                                        
#       
Note: Your version dates may be different depending on ship date and the image used.


This is a minimalistic initial ram filesystem that includes our specific utilities for the board, and is then used to bootstrap the Linux root. The initramfs is built into the kernel image so it cannot be modified without rebuilding the kernel, but it does include 8 bits for common configuration option we call soft jumpers.

For most development you will want to boot to the Debian filesystem which can be reached by typing "exit" through the serial or telnet console, or by removing the file /ts/fastboot while in Debian to make the board automatically boot to Debian.

2.3.1 Scripting in the initramfs

2.3.1.1 From on-board media (SD/NAND/eMMC)

A bash script at /ts/init can be created in order to run any custom scripting needed from the initramfs. This does not use the same $PATH as Debian, so all commands should have the full path to any applications called from this environment. The init file does not exist by default and must be created in order to be utilized. The initramfs looks for this file to be at the full path "/mnt/root/ts/init". The initramfs will automatically mount the Debian partition of the booted media and attempt to execute this file if it exists. This process happens near the end of the initramfs initialization, but before Debian is started; it is run in the foreground. Standard output and error are to the serial/telnet console, standard input is /dev/null for the script.

An example of the script would look like the following.

#!/bin/sh
 
/path/to/your/application &


2.3.1.2 From USB storage device (USB update mechanism)

For implementing a custom production process or applying updates in the field, this SBC is capable of detecting a USB device and running a script contained on it. The behavior of this process can be tuned, see the config information section below. The script must be named "tsinit", must be executable, and must be in the root directory of the first partition of the USB device. $PATH is passed to the tsinit script, it is what the initramfs environment $PATH is; if additional $PATHs are required they can be added in the tsinit script. It is recommended that the partition be formatted with ext2 or ext3. The process to execute this script happens near the end of the initramfs initialization, after the above /ts/init script, but before debian is started; it is run in the foreground. If a USB device exists, the first partition is mounted, and if the script file exists it is executed. The initramfs will by default mount the partition to "/mnt/usbdev/". Standard output and error are to the serial/telnet console, standard input is /dev/null.

An example of the script would look like the following.

#!/bin/sh
 
/path/to/your/application &


2.3.2 /mnt/root/ts/initramfs-xinit

Graphical applications should use /ts/initramfs-xinit. The xinit file is used to start up a window manager and any applications. The default initramfs-xinit starts a webbrowser viewing localhost:

#!/bin/sh
# Causes .Xauthority and other temp files to be written to /root/ rather than default /
export HOME=/root/
# Disables icewm toolbars
export ICEWM_PRIVCFG=/mnt/root/root/.icewm/
 
# minimalistic window manager
icewm-lite &
 
# this loop verifies the window manager has successfully started
while ! xprop -root | grep -q _NET_SUPPORTING_WM_CHECK
do
    sleep 0.1
done
 
# This launches the fullscreen browser.    If the xinit script ever closes, x11 will close.  This is why the last
# command is the target application which is started with "exec" so it will replace the xinit process id.
exec /usr/bin/fullscreen-webkit http://localhost


2.3.3 /mnt/root/ts/config

This config file can be used to alter many details of the initramfs boot procedure.

## This file is included by the early init system to set various bootup settings.
## if $jp7 is enabled none of these settings will be used.

## Used to control whether the FPGA is reloaded through software.
## 1 to enable reloading (default)
## 0 to disable reloading
#CFG_FPGARELOAD="0"

## By default dns-sd is started which advertises the ts<model>-<last 6 of mac>
## telnet and http services using zeroconf.
## 1 to enable dns-sd (default)
## 0 to disable dns-sd
#CFG_DNSSD_EN="0"

## This is used to discover hosts and advertise this host over multicast DNS.
## 1 to enable mdns (default)
## 0 to disable mdns
#CFG_MDNS_EN="0"

## ifplugd is started in the initramfs to start udhcpc, and receive an ipv4ll
## address.
## 1 to enable ifplugd (default)
## 0 to disable ifplugd
#CFG_IFPLUGD_EN="0"

## By default telnet is started on port 2323.
## 1 to enable telnet (default)
## 0 to disable telnet
#CFG_TELNET_EN="0"

## The busybox webserver is used to display a diagnostic web interface that can
## be used for development tasks such as rewriting the SD or uploading new
## software
## 1 to enable (default)
## 0 to disable
#CFG_HTTPD_EN="0"

## This eanbles a reset switch on DIO 29 (TS-7700), or DIO 9 on all of the
## boards.  Pull low to reset the board immediately.
## 1 to enable the reset sw (default)
## 0 to disable
#CFG_RESETSW_EN="0"

## The main debug console in the initramfs can be turned off. Since the console
## has no password protection, disabling it will prevent any access to it if
## the /ts/fastboot file is present, or is JP1 is on.
## 1 to enable the debug serial console (default)
## 0 to disable the debug serial console
#CFG_CONSOLE_EN="0"

## The console is forwarded through xuartctl which makes the cpu console available
## over telnet or serial console.
## 1 to enable network console (default)
## 0 to disable network console
#CFG_NETCONS_EN="0"

## By default Alsa will put the SGTL5000 chip into standby after 5 seconds of
## inactivity.  This is desirable in that it results in lower power consumption,
## but it can result in an audible popping noise.  This setting prevents
## standby so the pop is never heard.
## 1 to disable standby
## 0 to enable standby (default)
#CFG_SGTLNOSTBY="1"

## xuartctl is used to access the FPGA uarts.  By default it is configured to
## be IRQ driven which is optimized for best latency, but at the cost of
## additional CPU time.  You can reduce this by specifying a polling rate.
## The xuartctl process also binds to all network interfaces which can provide a
## simple network API to access serial ports remotely.  You can restrict this to
## the local network with the bind option.
## Configure XUART polling 100hz
## Default is IRQ driven
CFG_XUARGS="--irq=100hz"
## Configure xuartctl to bind on localhost
## Default binds on all interfaces
#CFG_XUARGS="--bind 127.0.0.1 --irq=100hz"
## For a full list of arguments, see the xuartctl documentation here:
## http://wiki.embeddedarm.com/wiki/Xuartctl#Usage

## By default the system will probe for up to 10s on USB for a mass storage device
## and mount the first partition.  If there is an executable /tsinit script in the
## root this will be executed.  This is intended for production or updates.
## 2 to enable USB init always (adds 10s or $CFG_USBTIME to startup)
## 1 to enable USB init when jp1=0 (default)
## 0 to disable USB init always
#CFG_USBINIT="0"

## The USB init script by default blocks for 10s to detect a thumb drive that
## contains the tsinit script.  Most flash media based drives can be detected
## in 3s or less.  Some spinning media drives can take 10s, or potentially longer.
## This options is the number of seconds to wait before giving up on the
## mass storage device.
#CFG_USBTIME="3"

### TS-8700
## Using the TS-8700 baseboard the board will by default initialze all of the
## ethernet ports as individual vlan ports, eg eth0.1, eth0.2, eth0,3, and eth0.4
## The alterantive option sets Port A to eth0.1, and Ports B-D to eth0.2, or
## you can configure all ethernet ports as a single eth0 port.
## See http://wiki.embeddedarm.com/wiki/TS-8700 for more information
## 2 disables any vlan and passes through all interfaces to eth0
## 1 enables "WLAN" mode setting "A" as eth0.1, and all others as eth0.2
## 0 enables "VLAN" mode for 4 individual ports (default)
#CFG_4ETH="1"

###TS-7670/TS-7400_V2
## DoubleStore as the root Debian filesystem is an option on the
## TS-7670/TS-7400_V2 that must be configured here.  This is only possible if
## the TS-7670/TS-7400_V2 is first booted from NAND, SDBoot jumper removed.
## The TS-7670 can use a 1 or 2 card DoubleStore dataset, while the TS-7400_V2
## can use only single card.  If this option is enabled, and no DoubleStore
## cards are present, the initramfs will fall back to mounting NAND as the root
## filesystem.
## 1 to use DoubleStore as rootfs when booted from NAND (default)
## 0 to always disable DoubleStore as the rootfs
#CFG_DBLSTOR_ROOT="0"

### TS-4712 / TS-4720
## These boards include an onboard switch with 2 external ports.  By default
## the switch will detect if it is on a known baseboard that supports the second
## ethernet switch port, and set up VLAN rules to define eth0.1 and eth0.2.  The
## other option is to configure the switch to pass through the packets to eth0
## regarless of port.
## 2 Disable VLAN and pass through to eth0
## 1 Enable VLAN on all baseboards
## 0 Enable VLAN on supported baseboards (Default)
#CFG_2ETH="1"

3 Debian Configuration

For development it is recommended to go to Debian on the SD card where there is plenty of space for development work. Debian provides many more packages and a much more familiar environment for users already versed in Debian. Once here you can use apt-get to install/remove packages, configure the network, and perform other common tasks. Out of the box the Debian distribution does not have a custom username/password set. You can use "root" as the username with no password to get access to the system. Keep in mind services such as ssh require a password set before they allow connection.

3.1 Configuring the Network

From almost any Linux system you can use "ip" or the ifconfig/route commands to initially set up the network. To configure the network interface manually you can use the same set of commands in the initramfs or Debian.

# 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 commonly networks will offer DHCP which can be set up with one command:

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

Configure DHCP in the initrd:

udhcpc -i eth0
# Or if you're on a baseboard with a second ethernet port, you can use that as:
udhcpc -i eth1

To make your network settings take effect on startup in Debian, edit /etc/network/interfaces:

 # Used by ifup(8) and ifdown(8). See the interfaces(5) manpage or 
 # /usr/share/doc/ifupdown/examples for more information.          
                                                                   
 # We always want the loopback interface.                          
 #                                                                 
 auto lo                                                           
 iface lo inet loopback                                            
                                                                   
 auto eth0                                                         
 iface eth0 inet static                                            
   address 192.168.0.50                                            
   netmask 255.255.255.0                                           
   gateway 192.168.0.1                                             
 auto eth1                                                         
 iface eth1 inet dhcp
Note: During Debian's startup it will assign the interfaces eth0 and eth1 to the detected mac addresses in /etc/udev/rules.d/70-persistent-net.rules. If the system is imaged while this file exists it will assign the new interfaces as eth1 and eth2. This file is generated automatically on startup, and should be removed before your first software image is created. The initrd network configuration does not use this file.

In this example eth0 is a static configuration and eth1 receives its configuration from the DHCP server. For more information on network configuration in Debian see their documentation here.

3.1.1 WIFI Client

This board optionally supports 802.11 through the WIFI-N-USB-2 module using the ath9k_htc driver.

Scan for a network

ifconfig wlan0 up
 
# Scan for available networks
iwlist wlan0 scan

In this case I'm connecting to "default" which is an open network:

          Cell 03 - Address: c0:ff:ee:c0:ff:ee
                    Mode:Managed
                    ESSID:"default"
                    Channel:2
                    Encryption key:off
                    Bit Rates:9 Mb/s

To connect to this open network:

iwconfig wlan0 essid "default"

You can use the iwconfig command to determine if you have authenticated to an access point. Before connecting it will show something similar to this:

# iwconfig wlan0
wlan0     IEEE 802.11bgn  ESSID:"default"  
          Mode:Managed  Frequency:2.417 GHz  Access Point: c0:ff:ee:c0:ff:ee   
          Bit Rate=1 Mb/s   Tx-Power=20 dBm   
          Retry  long limit:7   RTS thr:off   Fragment thr:off
          Encryption key:off
          Power Management:off
          Link Quality=70/70  Signal level=-34 dBm  
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:0   Missed beacon:0

If you are connecting using WEP, you will need to define a network key:

iwconfig wlan0 essid "default" key "yourpassword"

If you are connecting to WPA you will need to use wpa_passphrase and wpa_supplicant:

wpa_passphrase the_essid the_password > /etc/wpa_supplicant.conf

Now that you have the configuration file, you will need to start the wpa_supplicant daemon:

wpa_supplicant -Dwext -iwlan0 -c/etc/wpa_supplicant.conf -B

Now you are connected to the network, but this would be close to the equivalent of connecting a network cable. To connect to the internet or talk to your internal network you will need to configure the interface. See the #Configuring the Network for more information, but commonly you can just run:

dhclient wlan0
Note: Some older images did not include the "crda" and "iw" packages required to make a wireless connection. If you cannot get an ip address you may want to connect over ethernet and install these packages with "apt-get install crda iw -y".

3.1.2 Host a WIFI Access Point

The software image includes a build of compat-drivers from 3.8 so a large amount of wireless devices are supported. Some devices support AP/Master mode which can be used to host an access point. The WIFI-N-USB-2 module we provide also supports this mode.

First install hostapd to manage the access point:

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

Edit /etc/hostapd/hostapd.conf to include:

interface=wlan0
driver=nl80211
ssid=YourAPName
channel=1
Note: Refer to the kernel's hostapd documentation for more wireless configuration options.

To start the access point launch hostapd:

hostapd /etc/hostapd/hostapd.conf &

This will create a valid wireless access point, however many devices will not be able to connect without either a static connection, or a DHCP server. Refer to Debian's documentation for more details on DHCP configuration.

3.2 Installing New Software

Debian provides the apt-get system which lets you manage pre-built applications. Before you do this you need to update Debian's list of package versions and locations. This assumes you have a valid network connection to the internet.

Debian Squeeze has been moved to archive so you will need to update /etc/apt/sources.list to contain only these two lines:

 deb http://archive.debian.org/debian squeeze main
 deb-src http://archive.debian.org/debian squeeze main
apt-get update

For example, lets say you wanted to install openjdk for Java support. You can use the apt-cache command to search the local cache of Debian's packages.

 <user>@<hostname>:~# apt-cache search openjdk                                                                                  
 icedtea-6-jre-cacao - Alternative JVM for OpenJDK, using Cacao                                                           
 icedtea6-plugin - web browser plugin based on OpenJDK and IcedTea to execute Java applets                                 
 openjdk-6-dbg - Java runtime based on OpenJDK (debugging symbols)                                                        
 openjdk-6-demo - Java runtime based on OpenJDK (demos and examples)                                                      
 openjdk-6-doc - OpenJDK Development Kit (JDK) documentation                                                              
 openjdk-6-jdk - OpenJDK Development Kit (JDK)                                                                            
 openjdk-6-jre-headless - OpenJDK Java runtime, using Hotspot Zero (headless)                                             
 openjdk-6-jre-lib - OpenJDK Java runtime (architecture independent libraries)                                            
 openjdk-6-jre-zero - Alternative JVM for OpenJDK, using Zero/Shark                                                       
 openjdk-6-jre - OpenJDK Java runtime, using Hotspot Zero                                                                 
 openjdk-6-source - OpenJDK Development Kit (JDK) source files                                                            
 openoffice.org - office productivity suite                                                                               
 freemind - Java Program for creating and viewing Mindmaps                                                                
 default-jdk-doc - Standard Java or Java compatible Development Kit (documentation)                                       
 default-jdk - Standard Java or Java compatible Development Kit                                                           
 default-jre-headless - Standard Java or Java compatible Runtime (headless)                                               
 default-jre - Standard Java or Java compatible Runtime                                                                   

In this case you will likely want openjdk-6-jre to provide a runtime environment, and possibly openjdk-6-jdk to provide a development environment. You can often find the names of packages from Debian's wiki or from just searching on google as well.

Once you have the package name you can use apt-get to install the package and any dependencies. This assumes you have a network connection to the internet.

apt-get install openjdk-6-jre
# You can also chain packages to be installed
apt-get install openjdk-6-jre nano vim mplayer

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

3.3 Setting up SSH

On our boards we include the Debian package for openssh-server, but we remove the automatically generated keys for security reasons. To regenerate these keys:

dpkg-reconfigure openssh-server

Make sure your board is configured properly on the network, and set a password for your remote user. SSH will not allow remote connections without a password or a shared key.

passwd root

You should now be able to connect from a remote Linux or OSX system using "ssh" or from Windows using a client such as putty.

Note: If your intended application does not have a DNS source on the target network, it can save login time to add "UseDNS no" in /etc/ssh/sshd_config.

3.4 Starting Automatically

From Debian the most straightforward way to add your application to startup is to create a startup script. This is an example simple startup script that will toggle the red led on during startup, and off during shutdown. In this case I'll name the file customstartup, but you can replace this with your application name as well.

Edit the file /etc/init.d/customstartup to contain this:

 #! /bin/sh
 # /etc/init.d/customstartup
 
 case "$1" in
   start)
     /path/to/your/application
     ## If you are launching a daemon or other long running processes
     ## this should be started with
     # nohup /usr/local/bin/yourdaemon &
     ;;
   stop)
     # if you have anything that needs to run on shutdown
     /path/to/your/shutdown/scripts
     ;;
   *)
     echo "Usage: customstartup start|stop" >&2
     exit 3
     ;;
 esac
 
 exit 0
Note: The $PATH variable is not set up by default in init scripts so this will either need to be done manually or the full path to your application must be included.

To make this run during startup and shutdown:

update-rc.d customstartup defaults

To manually start and stop the script:

/etc/init.d/customstartup start
/etc/init.d/customstartup stop

While this is useful for headless applications, if you are using X11 you should modify "/usr/bin/default-x-session":

#!/bin/sh
 
export HOME=/root/
export ICEWM_PRIVCFG=/mnt/root/root/.icewm/
 
icewm-lite &
 
while ! xprop -root | grep -q _NET_SUPPORTING_WM_CHECK
do
    sleep 0.1
done
 
exec /usr/bin/fullscreen-webkit http://127.0.0.1

Replace fullscreen-webkit with your own graphical application.

4 Backup / Restore

If you are using a Windows workstation there is no support for writing directly to block devices. However, as long as one of your booting methods still can boot a kernel and the initrd you can rewrite everything by using a usb drive. This is also a good way to blast many stock boards when moving your product into production. You can find more information about this method with an example script here.

Note: Note that the MBR installed by default on this board contains a 446 byte bootloader program that loads the initial power-on kernel and initrd from the first and second partitions. Replacing it with an MBR found on a PC would not work as a PC MBR contains an x86 code bootup program.

4.1 MicroSD Card

MicroSD.png Click to download the latest 4GB SD card image.

Using another Linux workstation

If you do not have an SD card that can boot to the initramfs, you can download the latest SD card image and rewrite this from a Linux workstation. A USB MicroSD adapter can be used to access the card. First, you must find out which /dev/ device corresponds with your USB reader/writer.

Step 1 Option 1 (lsblk)


Newer distributions include a utility called "lsblk" which allows simple identification of the intended card:

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. Note that on your system, sdX will not be 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.

Step 1 Option 2 (dmesg)


After plugging in the device, you can use dmesg to list

 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, sdXc is shown as a 3.97GB card. Note that on your system, sdX will not be 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.

Step 2


Once you have the target /dev/ device you can use "dd" to backup/restore the card. To restore the board to stock, or rewrite to the latest SD image:

wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7670-linux/binaries/ts-images/ts7670_7400v2-latest.dd.bz2
 
# Specify your block device instead of /dev/sdX
# Note that this is a whole disk image, so use /dev/sdX instead of
# using /dev/sdX1
bzcat ts7670_7400v2-latest.dd.bz2 | dd conv=fsync bs=4M of=/dev/sdX

To take a backup of your entire SD card, you can switch the input file and the output file:

# Specify your block device instead of /dev/sdX
dd if=/dev/sdX conv=fsync bs=4M | bzip2 > backup.dd.bz2

4.2 NAND Flash

The NAND is divided in to three devices, mtd0, mtd1, and mtd2. mtd0 contains the raw bootstream (kernel and initramfs in one binary), mtd1 contains what would normally be the /ts folder on the SD card, and mtd2 contains the linux root filesystem (mtd1 and mtd2 use UBI and UBIFS and can be subdivided down further with mechanisms in UBIFS, see UBI and UBIFS for more information). Since UBI/UBIFS does have a fairly linear mount time for device size, mtd1 is made fairly small, 8MB. This allows for increased startup speed when booting from NAND so that configuration, FPGA softload, or other scripts may be run as soon as possible after power is applied.

4.2.1 Kernel

When the kernel is built and installed to the SD card from a host PC, the script also copies the newly built bootstream file to the linux partition, to /lib/modules/imx28_ivt_linux.sb. The bootstream is a Freescale boot mechanism that contains the bootloader and kernel all in one binary. When booted from an SD card, the bootstream at /lib/modules/imx28_ivt_linux.sb can be flashed to mtd0 with

kernel_from_sd

This will take a few moments and then will return with no messages if everything was successful.

The following command can be used to update the kernel on NAND from the imx28_ivt_linux.sb file from USB:

kernel_from_usb

The file is expected to be located at /mnt/usbdev/imx28_ivt_linux.sb, the command is intended for use with our USB update mechanism. The file can be copied from the Debian partition of a bootable SD card, /lib/modules/imx28_ivt_linux.sb; or directly from a kernel build, /<kernel_tree>/imx-bootlets-src-10.12.01/imx28_ivt_linux.sb.

See the section on our USB update mechanism for more information about utilizing this process.

4.2.2 Filesystem

Making a UBIFS Debian image from existing filesystem is the best way to make a custom image for production devices. Technologic Systems strongly recommends doing all development on an SD card; later, create a UBIFS image from that Debian filesystem. Copying the large amount of small files on the Debian filesystem directly to or from the NAND device is very time consuming.

In order to create a UBIFS image from a host PC mtd-utils will need to be installed, please see your distribution's documentation for instructions on installation

#/mnt/source_fs_root is the mounted Debian filesystem on an SD; /mnt/usb is a USB drive to store the image for later use
mkfs.ubifs -m4096 -e516096 -c3861 -r /mnt/source_fs_root/ nandimg.ubifs

Note that the UBI rootfs partition on NAND is 1900MiB, Make sure that the UBIFS image is smaller than this. UBI does implement compression on-disk, so the total size of a folder tree may not reflect the actual filesystem size when made in to a UBIFS image. For example, our default SD Debian root filesystem is around 1.2GB, however when made in to a UBIFS image with the above command, it is compressed to roughly 550MB and remains this size on disk.


The latest UBIFS image can be found on our FTP site.


This NAND UBIFS image can be used in conjunction with tools in our initramfs to flash the NAND device.

Copy nandimg.ubifs to the root Debian folder (partition 2) of a pre-imaged bootable SD card. The SD card can either be a freshly imaged SD card, or be one that was used for current development, provided that there is enough space to fit the UBIFS image. Boot from the SD card to the initramfs, when presented a command prompt, run the following command:

filesystem_from_sd

Output from the command will look like the following:

prog_ok=1

The following command can be used to flash the UBIFS image to NAND:

filesystem_from_usb

The UBIFS image file is expected to be located at /mnt/usbdev/nandimg.ubifs, the command is intended for use with our USB update mechanism.


WARNING: The `filesystem_from_*` commands will completely format any existing data that is on the NAND linux root partition



Using filesystem_from_usb when booted from NAND

While there is no issue in executing filesystem_from_usb when booted from SD (provided there are no flash partitions mounted), further preparation is required in order to successfully boot from eMMC/NAND, and use the USB update functionality to update the flash. A USB device is required to have the the Debian distribution on the first partition and a specific set of steps in the "tsinit" script - this ensures that all flash partitions are safely unmounted and the necessary tools are available. See the initramfs USB scripting section for more information on setting up the "tsinit" script.

Using a linux host PC, format a USB drive with the first partition (min. 2GB) formatted ext2/3. Download the distribution tarball and extract it to first partition of the USB drive.

Next, set up the "tsinit" file with the following script outline:

#!/bin/sh
 
#We only need unmount /mnt/root and use USB if booted from NAND/eMMC
if [ "$bootmode" == "0x1" ]; then
  killall mdnsd >/dev/null #Required to cleanly umount /etc
  sleep 1
  if [ -e /dev/mtd0 ]; then
    umount /mnt/root/ts
  fi
  umount /etc
  umount /mnt/root
 
  mount -obind /mnt/usbdev /mnt/root
  mount -obind /mnt/root/etc /etc/
fi
 
echo ""
source /ts.subr
tshwctl --greenledon --redledon
echo "Flashing kernel"
kernel_from_usb >/dev/null 2>&1
if [ "$?" != "0" ]; then
  echo "Failed flashing kernel"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
echo "Flashing filesystem"
eval `filesystem_from_usb`
if [ "$prog_ok" != "1" ] ; then
  echo "Failed flashing filesystem"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
 
#We only need unmount /mnt/root and use USB if booted from NAND
if [ "$bootmode" == "0x1" ]; then
  umount /etc
  umount /mnt/root
fi
 
echo "Done"
while true; do tshwctl --greenledon; sleep .5; tshwctl --greenledoff; sleep .5 ; done &

Be sure to copy nandimg.ubifs and imx28_ivt_linux.sb to the root directory of the first partition of the USB drive as well!

Note, if you wish to integrate this in to your own custom USB update script, the critical sections for setting up this process are surrounded by the if blocks that check for NAND being the bootdev.

The above script will keep both LEDs on and solid while the process is happening, and will blink the green or red LED upon success or fail of the imaging process. Upon completion a power cycle or reboot is required if booted from NAND to run the update.

There are a number of different configurations and setups available when using UBI and UBIFS, see UBI and UBIFS for more information about the capabilities of the subsystem.

4.3 eMMC

Note: The TS-7400-V2 only has eMMC on PCB Rev. B and newer. For TS-7400-V2 Rev. A, see the NAND Flash section. For PCB revision information, see the PCB Revisions section.

The eMMC device is set up like a standard SD card when presented to the system, however it does have a few differences. eMMC offers "enhanced mode" which makes the usually MLC device behave like an SLC device. This setting does decrease the effective device size, however the benefit of reliability greatly makes up for it. Another option that eMMC offers is "write reliability." This setting changes the internal behavior of the eMMC, meaning that if a power-off occurs during a write, the guaranteed loss is limited to the currently written 512 byte sector. Aside from those two settings, the device will appear as a standard SD card, with the same partition setup as our standard SD card size, save for the maximum size of the linux partition, the second partition. The first partition contains the raw bootstream (kernel and initramfs in one binary blob); the second partition houses the Debian linux filesystem.

4.3.1 Kernel

Due to the way the freescale bootlets work, the easiest way to get a kernel on the eMMC device is to use a direct `dd` image of a bootable SD card. In order to create a `dd` image, use the following command on a bootable SD card:

dd if=/dev/sdX1 of=kernelpart.dd

Replace /dev/sdX1 with the first partition of a bootable SD card. The file "kernelpart.dd" can then be copied to the first partition of a USB drive and used in conjunction with kernel_from_usb below. This step is not necessary if using kernel_from_sd.


If a bootable SD card is in slot 0, the following command can be used when booted from either said SD card, or eMMC:

kernel_from_sd

In using a USB device to update the kernel of the eMMC, the process is slightly different. The following script expects the file /mnt/usbdev/kernelpart.dd The kernelpart.dd file is created by using the `dd` command as stated above.

kernel_from_usb

Both scripts above will take a few moments and will return with an exit of 0, and print "prog_ok=1" upon success. This command will also destroy and re-create the partition table. As long as the factory partition scheme is used, this command is safe to run without having to update the eMMC filesystem as well.


See the section on our USB update mechanism for more information about utilizing this process.

4.3.2 Filesystem

The process to update the filesystem on eMMC simply uses a tarball of the desired linux filesystem. Technologic Systems strongly recommends to do all development on an SD card and later create a tarball from that Debian filesystem. This allows for easy creation of a tarball from the existing master SD card to be used in production processes.

The tarball can be created from an existing filesystem. A command like the following should be all that is needed.

tar cvf rootfs.tar -C /mnt/source_fs_root/ .

This command will create rootfs.tar in the current directory from the filesystem tree root located at /mnt/source_fs_root/ Many implementations of `tar` will not have issues with creating the output file in the same directory as input. However it is recommended to keep the output file in a different directory than the source, just in case.

This tarball can be used in conjunction with scripts in our initramfs to flash the eMMC device.


Copy rootfs.tar to the root Debian folder (partition 2) of a bootable SD card. Be sure there is enough space available. Our standard image has enough free space to allow this. Boot from the SD card to the initramfs, and use the following command:

filesystem_from_sd

Alternatively, the rootfs.tar can be copied to the root directory of the first partition of a USB drive:

filesystem_from_usb

In this case, the script expects the file /mnt/usbdev/rootfs.tar to exist.


Output from the commands will look like the following:

prog_ok=1


WARNING: The `filesystem_from_*` commands will completely format any existing data that is on the eMMC linux root partition


Using *_from_usb when booted from eMMC

Since part of this process will modify an active partition table in the eMMC, this script is required for updating either the kernel or the filesystem when booted from eMMC.

While there is no issue in executing filesystem_from_usb when booted from SD (provided there are no flash partitions mounted), further preparation is required in order to successfully boot from eMMC/NAND, and use the USB update functionality to update the flash. A USB device is required to have the the Debian distribution on the first partition and a specific set of steps in the "tsinit" script - this ensures that all flash partitions are safely unmounted and the necessary tools are available. See the initramfs USB scripting section for more information on setting up the "tsinit" script.

Using a linux host PC, format a USB drive with the first partition (min. 2GB) formatted ext2/3. Download the distribution tarball and extract it to first partition of the USB drive.

Next, set up the "tsinit" file with the following script outline:

#!/bin/sh
 
#We only need unmount /mnt/root and use USB if booted from NAND/eMMC
if [ "$bootmode" == "0x1" ]; then
  killall mdnsd >/dev/null #Required to cleanly umount /etc
  sleep 1
  if [ -e /dev/mtd0 ]; then
    umount /mnt/root/ts
  fi
  umount /etc
  umount /mnt/root
 
  mount -obind /mnt/usbdev /mnt/root
  mount -obind /mnt/root/etc /etc/
fi
 
echo ""
source /ts.subr
tshwctl --greenledon --redledon
echo "Flashing kernel"
kernel_from_usb >/dev/null 2>&1
if [ "$?" != "0" ]; then
  echo "Failed flashing kernel"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
echo "Flashing filesystem"
eval `filesystem_from_usb`
if [ "$prog_ok" != "1" ] ; then
  echo "Failed flashing filesystem"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
 
#We only need unmount /mnt/root and use USB if booted from NAND
if [ "$bootmode" == "0x1" ]; then
  umount /etc
  umount /mnt/root
fi
 
echo "Done"
while true; do tshwctl --greenledon; sleep .5; tshwctl --greenledoff; sleep .5 ; done &

Be sure to copy kernelpart.dd and rootfs.tar to the root directory of the first partition of the USB drive as well!

Note, if you wish to integrate this in to your own custom USB update script, the critical sections for setting up this process are surrounded by the if blocks that check the bootdev. These sections will unmount the root filesystem and then mount the USB drive as the new root filesystem. This allows the contents of the eMMC device to be completely re-written with tools available in Debian without having the eMMC device mounted.

The above script will keep both LEDs on and solid while the process is happening, and will blink the green or red LED upon success or fail of the imaging process. Upon completion a power cycle or reboot is required if booted from NAND to run the update.

5 Software Development

Most of our examples are going to be in C, but Debian will include support for many more programming languages. Including (but not limited to) C++, PERL, PHP, SH, Java, BASIC, TCL, and Python. Most of the functionality from our software examples can be done from using system calls to run our userspace utilities. For higher performance, you will need to either use C/C++ or find functionally equivalent ways to perform the same actions as our examples. Our userspace applications are all designed to go through a TCP interface. By looking at the source for these applications, you can learn our protocol for communicating with the hardware interfaces in any language.

The most common method of development is directly on the SBC. Since debian has space available on the SD card, we include the build-essentials package which comes with everything you need to do C/C++ development on the board.


Editors

Vim is a very common editor to use in Linux. While it isn't the most intuitive at a first glance, you can run 'vimtutor' to get a ~30 minute instruction on how to use this editor. Once you get past the initial learning curve it can make you very productive. You can find the vim documentation here.

Emacs is another very common editor. Similar to vim, it is difficult to learn but rewarding in productivity. You can find documentation on emacs here.

Nano while not as commonly used for development is the easiest. It doesn't have as many features to assist in code development, but is much simpler to begin using right away. If you've used 'edit' on Windows/DOS, this will be very familiar. You can find nano documentation here.

Compilers

We only recommend the gnu compiler collection. There are many other commercial compilers which can also be used, but will not be supported by us. You can install gcc on most boards in Debian by simply running 'apt-get update && apt-get install build-essential'. This will include everything needed for standard development in c/c++.

You can find the gcc documentation here. You can find a simple hello world tutorial for c++ with gcc here.

Build tools

When developing your application typing out the compiler commands with all of your arguments would take forever. The most common way to handle these build systems is using a make file. This lets you define your project sources, libraries, linking, and desired targets. You can read more about makefiles here.

If you are building an application intended to be more portable than on this one system, you can also look into the automake tools which are intended to help make that easier. You can find an introduction to the autotools here.

Cmake is another alternative which generates a makefile. This is generally simpler than using automake, but is not as mature as the automake tools. You can find a tutorial here.

Debuggers

Linux has a few tools which are very helpful for debugging code. The first of which is gdb (part of the gnu compiler collection). This lets you run your code with breakpoints, get backgraces, step forward or backward, and pick apart memory while your application executes. You can find documentation on gdb here.

Strace will allow you to watch how your application interacts with the running kernel which can be useful for diagnostics. You can find the manual page here.

Ltrace will do the same thing with any generic library. You can find the manual page here.

5.1 Cross Compiling

While it is recommend to develop entirely on the SBC itself, it is also possible to develop from an x86 compatible Linux system using a cross compiler. For this SBC use the cross compiler located here. The resulting binary will be for ARM.

[user@localhost]$ /path/to/arm-fsl-linux-gnueabi/bin/arm-linux-gcc hello.c -o hello
[user@localhost]$ file hello
hello: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), not stripped

This is one of the simplest examples. For working with a larger project a Makefile will typically be used. More information about Makefiles is available here. Another common requirement is linking to third party libraries provided by Debian on the SBC. There is no exact set of steps for every project when cross compiling, but the process will be very much the same. Provide the cross compiler with access to the necessary headers, libraries, and source files, and install the binary on the target. The following example will link to sqlite from Debian.

Install the sqlite library and header on the SBC:

apt-get update && apt-get install -y libsqlite3-0 libsqlite-dev

This will fetch the binaries from the internet and install them on the SBC. The installed files can then be listed with dpkg:

dpkg -L libsqlite3-0 libsqlite3-dev

The needed files from this output will be the .h and .so files, they will need to be copied to the project directory on the cross-compling host.

See the example with libsqlite3 below. This is not intended to provide any functionality, but just call functions provided by sqlite.

#include <stdio.h>
#include <stdlib.h>
#include "sqlite3.h"
 
int main(int argc, char **argv)
{
	sqlite3 *db;
	char *zErrMsg = 0;
	int rc;
	printf("opening test.db\n");
	rc = sqlite3_open("test.db", &db);
	if(rc){
		fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db));
		sqlite3_close(db);
		exit(1);
	}
	if(rc!=SQLITE_OK){
		fprintf(stderr, "SQL error: %s\n", zErrMsg);
	}
	printf("closing test.db\n");
	sqlite3_close(db);
	return 0;
}

To build this with the external libraries the makefile below can be used. This will have to be adjusted for the proper toolchain path. In this example, the headers are located in external/include and the library in external/lib.

CC=/opt/arm-2008q3/bin/arm-none-linux-gnueabi-gcc
CFLAGS=-c -Wall
 
all: sqlitetest
 
sqlitetest: sqlitetest.o
        $(CC) sqlitetest.o external/lib/libsqlite3.so.0 -o sqlitetest
sqlitetest.o: sqlitetest.c
        $(CC) $(CFLAGS) sqlitetest.c -Iexternal/include/
 
clean:  
        rm -rf *o sqlitetest.o sqlitetest

The resulting binary can be copied to the target and executed. There are many ways to transfer the compiled binaries to the board. Using a network filesystem such as sshfs or NFS will be the simplest to use if needed frequently during development, but will require a setup. See the host linux distribution's manual for more details. The simplest network method is using ssh/sftp. If running Windows, winscp can be used, or just scp in linux. Make sure a password is set for a user account, root or otherwise, in order to properly ssh or scp files to the target. From winscp, enter the ip address of the SBC, the root username, and the password; this will create an explorer window that can use drag-and-drop of files to copy them to the target.

For scp in linux, run:

#replace with the binary name and the SBC IP address
scp sqlitetest root@192.168.0.50:/root/

After transferring the file to the board, execute it:

ts:~# ./sqlitetest 
opening test.db
closing test.db

5.2 Compile the Kernel

For adding new support to the kernel, or recompiling with more specific options you will need to have an x86 compatible Linux host available that can handle the cross compiling. Compiling the kernel on the board is not supported or recommended. Before building the kernel you will need to install a few support libraries on your workstation:

Prerequisites

RHEL/Fedora/CentOS:

yum install ncurses-devel ncurses
yum groupinstall "Development Tools" "Development Libraries"


Ubuntu/Debian:

sudo apt-get install build-essential libncurses5-dev libncursesw5-dev git


If you are on a 64-bit system, then 32-bit libraries will be required for the toolchain, for newer Debian and Ubuntu distrubutions with Multiarch support, use the command:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6-dev:i386 zlib1g-dev:i386

On older distributions:

sudo apt-get install ia32-libs


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


Download sources and configure

git clone https://github.com/embeddedarm/linux-2.6.35.3-imx28.git
cd linux-2.6.35.3-imx28/
 
# This sets up the default configuration that we ship with
make ts7400_defconfig
ln -sf initramfs.cpio-ts7400 initramfs.cpio

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.

make

Build bootstream

The i.MX28 utilizes what Freescale calls a "bootstream," this is a series of "bootlets" that are all put together in a binary blob. The default bootstream sets up RAM, power, and contains the kernel to be run. Every time a kernel is rebuilt, a new bootstream must be compiled containing the new kernel image. The following script is used to take the newly built kernel and output a bootstream for the SD card:

./build_bootstream

This will create imx-bootlets-src-10.12.01/imx28_ivt_linux.sb The .sb file is the standard image used for the SD card and NAND.

Building External Wireless Modules

In order to support the wide range of USB wifi modules that Technologic Systems has offered over the years, the compat-wireless project is used to build all compatible modules. A simple command is used to build them:

./build_wireless

Install the bootstream (kernel/initramfs) and Modules

Next you need to install the kernel and modules to the SD card. Freescale uses a specialized booting mechanism for their processor, so to simplify installation we provide two scripts to handle installation of the kernel+bootstream, kernel modules, headers, and compat-wireless modules.

For example, if your workstation's SD card is /dev/mmcblk0:

./install_bootstream imx-bootlets-src-10.12.01/imx28_ivt_linux.sb mmcblk0 p1
./install_hdr_mod mmcblk0p2

If your workstation's SD card is /dev/sdc:

./install_bootstream imx-bootlets-src-10.12.01/imx28_ivt_linux.sb sdc 1
./install_hdr_mod sdc2


Note: On newer linux distributions, the output of 'fdisk' has changed. If the unit fails to boot after a compile, take a look at the output of the './install_bootstream ... ' command. If the line
./install_bootstream: line 122: [: !=: unary operator expected

is printed, then you need to apply the patch to fix this. Use the following command to apply the patch:

patch -p1 < install_bootstream-newer-fdisk.patch


5.2.1 Linux 3.14

Note: The 3.14 kernel is intended to be used with the Rev B PCB. While it is compatible with the Rev A, NAND will not function at all, and ethernet will need a manual reset with the following commands:


tshwctl --clrdio 2_9
tshwctl --clrdio 0_21
sleep .015
tshwctl --setdio 2_9


3.14 kernel support has been brought to the TS-7400-V2. All of the software remains the same except for two notes of interest as pointed out below. There is a small update to the initramfs and tshwctl to accommodate the newer kernel, however only the kernel compile process as outlined below needs to be followed in order to update those as needed. Be sure to image an SD card with the latest image available before running through this process.


There are two notes that should be heeded for updating to 3.14:

  • The WDT feed process has changed, the 3.14 kernel supports the WDT in kernel. The WDT is still provided by the microcontroller as an external WDT for added safety. Do not use the WDT instructions in this manual, as this can lead to unpredictable results. See this page for more information on using the WDT in the 3.14 kernel.
  • The RTC now has a kernel interface. It is a standard /dev/rtc device as presented by the kernel. There is no need to use 'tshwctl --getrtc' or 'tshwctl --setrtc' however they can still be used. The use of 'tshwctl --nvram' is unaffected and should still be used in the same manner.


For adding new support to the kernel, or recompiling with more specific options you will need to have an x86 compatible Linux host available that can handle the cross compiling. Compiling the kernel on the board is not supported or recommended. Before building the kernel you will need to install a few support libraries on your workstation:

Prerequisites

All systems:

Download and unpack the cross compiler

wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7680-linux/cross-toolchains/imx28-cross-glibc.tar.bz2
tar xvf imx28-cross-glibc.tar.bz2 -C /path/to/folder/

/path/to/folder can be any directory so long as the current user has permissions to write to it. Remember this path as its used later during the kernel build procedure.


RHEL/Fedora/CentOS:

yum install ncurses-devel ncurses
yum groupinstall "Development Tools" "Development Libraries"


Ubuntu/Debian:

sudo apt-get install build-essential libncurses5-dev libncursesw5-dev git


If you are on a 64-bit system, then 32-bit libraries will be required for the toolchain, for newer Debian and Ubuntu distrubutions with Multiarch support, use the command:

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6-dev:i386 zlib1g-dev:i386

On older distributions:

sudo apt-get install ia32-libs


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


Download sources and configure

git clone https://github.com/embeddedarm/linux-3.14.28-imx28.git
cd linux-3.14.28-imx28/
 
# Switch to the branch specific for this SBC
git checkout 7400-7670
 
# These next commands set up some necessary environment variables
export ARCH=arm
export CROSS_COMPILE=/path/to/folder/arm-fsl-linux-gnueabi/bin/arm-linux-
export LOADADDR=0x40008000
 
# This sets up the default configuration
make ts7400_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. Since 3.14 uses Device Tree, and the Freescale bootloader is not set up to handle that, an additional preparation step is needed as well to append the binary device tree to the end of the kernel binary.

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.

Next, the correct DTB needs to be appended to the zImage binary. However, because of the way the Freescale bootloader detects and passes RAM, it is not compatible with the kernel Device Tree. Therefore, there are two DTB files, one to specify 128 MB of RAM, and the other for 256 MB. The 128 MB variant will boot on both, however on a system with an actual 256 MB of RAM, only 128 MB of that will be accessible. On the other hand, the 256 MB DTB is only compatible with a TS-7400-V2 that has 256 MB of RAM; it will not boot on a unit with 128 MB.

cat arch/arm/boot/zImage arch/arm/boot/dts/imx28-ts7400-128M.dtb > zImage

Or:

cat arch/arm/boot/zImage arch/arm/boot/dts/imx28-ts7400-256M.dtb > zImage

And now, move the zImage back to its expected location:

mv zImage arch/arm/boot/


Build bootstream

The i.MX28 utilizes what Freescale calls a "bootstream," this is a series of "bootlets" that are all put together in a binary blob. The default bootstream sets up RAM, power, and contains the kernel to be run. Every time a kernel is rebuilt, a new bootstream must be compiled containing the new kernel image. The following script is used to take the newly built kernel and output a bootstream for the SD card:

./build_bootstream

This will create imx-bootlets-src-10.12.01/imx28_ivt_linux.sb The .sb file is the standard image used for the SD card.

Install the bootstream (kernel/initramfs), headers, and modules

Next you need to install the kernel and modules to the SD card. We provide a simple script to copy the kernel uImage file, kernel modules, and headers to the SD card to update everything at once.

For example, if your workstation's SD card is /dev/mmcblk0:

./install_bootstream imx-bootlets-src-10.12.01/imx28_ivt_linux.sb mmcblk0 p1
./install_hdr_mod mmcblk0p2


If your workstation's SD card is /dev/sdc:

./install_bootstream imx-bootlets-src-10.12.01/imx28_ivt_linux.sb sdc 1
./install_hdr_mod sdc2


Note: On newer linux distributions, the output of 'fdisk' has changed. If the unit fails to boot after a compile, take a look at the output of the './install_bootstream ... ' command. If the line
./install_bootstream: line 122: [: !=: unary operator expected

is printed, then you need to apply the patch to fix this. Use the following command to apply the patch:

patch -p1 < install_bootstream-newer-fdisk.patch

5.3 Using the Oracle JRE

Oracle provides a headless JRE binary for the ARMv5 processor series which is compatible with this processor. In many cases the OpenJDK JRE is sufficient for an application, but Oracle's JRE provides better performance. To install this JRE, first accept the license and download this from Oracle here.

Your version number may be slightly different, but the process should remain the same:

tar -xf ejre-7u45-fcs-b15-linux-arm-sflt-headless-26_sep_2013.tar.gz
mv ejre1.7.0_45/ /usr/share/oracle-jre/
ln -s /usr/share/oracle-jre/bin/java /usr/bin/java

You can verify this is installed by checking the version:

root@ts:~# java -version
java version "1.7.0_45"
Java(TM) SE Embedded Runtime Environment (build 1.7.0_45-b15, headless)
Java HotSpot(TM) Embedded Client VM (build 24.45-b08, mixed mode)

6 Features

6.1 ADC

The i.MX28 CPU provides 4 channels of LRADC, 12bit, with an absolute accuracy limited to 0.5% due to the implementation in the CPU. The TS-7400-V2 is configured to support 0-3.3V inputs. In order to read the channels that are connected, use the following command:

tshwctl --cpuadc

The command will return output similar to the following:

LRADC_ADC1_millivolts=12
LRADC_ADC2_millivolts=10
LRADC_ADC3_millivolts=10
LRADC_ADC4_millivolts=3240
LRADC_ADC6_millivolts=6072

The output channels are the CPU pin names themselves, and the value is the voltage represented in mV. A single execution of `tshwctl --cpuadc` takes around 10 ms real time. Integrating the source in to your own application can surely increase this acquisition speed. The LRADC has a maximum sample cycle of 428 kHz, all selected channels are sampled simultaneously on the same clock and processed round-robin, with each channel generating an interrupt upon conversion completion.

For more information about the LRADC, refer to the CPU manual.

6.2 Battery Backed RTC and Temperature Sensor

This board includes a temperature compensating RTC which maintains ±5 ppm between 0C to +85C. This is accessed in software using tshwctl. By default, tshwctl will run "tshwctl --getrtc" on startup which will pull system time from the RTC, and set the system time. During the Technologic Systems production process the RTC will be programmed with an accurate time.

If time ever needs to be set you can run:

tshwctl --setrtc

This will take the system time and write it to the RTC. The battery in the RTC will last approximately 10 years for most applications, but the RTC allows you to see when the battery reaches low or critical voltages:

# tshwctl --rtcinfo             
rtc_present=1                   
rtctemp_millicelsius=36000      
rtcinfo_oscillator_ok=1         
rtcinfo_batt_low=0         
rtcinfo_batt_crit=0         
rtcinfo_firstpoweroff=0000000000
rtcinfo_lastpoweron=0000000000

rtcinfo_oscillator_ok is true when the RTC is operational and time is being kept
rtcinfo_batt_low is true when the battery is less than 2.805v (85% of 3.3v)
rtcinfo_batt_crit is true when the batter is less than 2.475v (75% of 3.3v)

Note: While the RTC will remain operational with a battery voltage down to 1.8v, the lithium battery used has a very steep discharge curve. Once the battery reaches critical level it should be replaced.

rtcinfo_first/lastpoweroff/on are two registers that denote the first time the RTC started using battery power, and the last time power was restored and the RTC stopped using battery power for timekeeping. The output of these registers is in the format MMDDhhmmss. Once `tshwctl --rtcinfo` is called, these registers are cleared and able to be set again. This is a great tool to check if a power off has occurred and how long it lasted.

6.3 CAN

The TS-7400_V2 i.MX286 CPU has two FlexCAN ports that use the linux SocketCAN implementation. Please note that the TS-7400-V2 CAN1 port does not have a CAN transceiver, and CAN0 may or may not have one depending on options ordered with the unit. The ports can be set up and used with the following commands:

#Note that the following command is only necessary on the October 2, 2013 TS-7670/TS7400_V2 image.
devmem 0x80018110 32 0x3ff5f5f
modprobe flexcan
ifconfig can0 up
ifconfig can1 up

In order to set the baud rate of either CAN interface, the interface must first be brought down with:

ifconfig canX down

Where "X" is interface 0 or 1. At this point, the desired baud rate can be directly entered in to the file "/sys/devices/platform/FlexCAN.X/bitrate", where X is the desired interface. For example, to set a baud rate of 750kHz on both interfaces:

echo 750000 > /sys/devices/platform/FlexCAN.0/bitrate
echo 750000 > /sys/devices/platform/FlexCAN.1/bitrate

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

candump can0 &
cansend can1 can1 7DF#03010C
#This command will return
  can0  7DF  [3] 03 01 0C

Note: It has been observed that the flexCAN driver present in the 2.6.35 kernel has some issues. If your application is running in to these issues, please see the discussion thread here: https://community.nxp.com/thread/272930 Apply the mentioned patch and compile the kernel. The patch is also included in our kernel git repo. Be sure after the patch is applied to set the kernel config options CONFIG_CAN_DEV, CONFIG_CAN_CALC_BITTIMING, and CONFIG_CAN_FLEXCAN. They can be modules or built-in.


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 using C-types, Java using JNI.

6.4 CPU

This board features the i.MX286 454MHz ARM9 from Freescale. For more information about the processor and it's included peripherals, refer to the CPU manual.

6.4.1 CPU Frequency

The i.MX28 CPU can run at multiple frequencies. By default the CPU runs at maximum speed, 454 MHz, but can be lowered for power savings.

See current speed:

cat /sys/devices/system/cpu/cpu0/cpufreq/cpuinfo_cur_freq
454736   # Default speed


Set speed to lowest:

echo 261818 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed


Set speed to highest:

echo 454736 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed


6.5 DIO

This board uses CPU DIO, typically there are 4 functions associated with each physical pin (I2C, PWM, SPI, DIO, etc). See the CPU manual for the complete listing and for information on how to control these DIO.

Note that most of the pins start in their "Function" mode and must be set to DIO mode to be able to be used as DIO. Be aware that doing this on a running system may have adverse effects if there are kernel drivers trying to use specific pins in their peripheral mode(s).

DIO numbers are referenced in bank_pin notation in the table below. This makes associating pins with DIO registers much simpler when looking at the manual. The example code below is also based around using the bank and pin notation.

DIO can be directly manipulated with tshwctl, for example:

tshwctl --setdio 3_25 #Set pin 1 of the 26 pin header high
tshwctl --clrdio 0_17 #Turn on the red LED by setting the pin low
tshwctl --getdio 1_16,1_17 #Get the input state of pin 1 and 3 of the 44 pin header

See the end of this section for example software to manipulate DIO pins.

6.5.1 Upper header pin-out (26-pin)

Pin # Name Function
1 I2C_DAT CPU DIO3_25 or I2C Data
2 M0_SW_CLK Reserved
3 GND Ground
4 M0_SW_DIO Reserved
5 CPU DIO1_7 CPU DIO1_7
6 I2C_CLK CPU DIO3_24 or I2C Clock
7 DEBUG_TXD Debug UART TXD
8 DEBUG_RXD Debug UART RX
9 SPI_MISO [1] CPU DIO2_4 or SPI MISO
10 AUX 3.3V 3.3V Output
11 CPU DIO1_8 CPU DIO1_8
12 SPI_MOSI [1] CPU DIO2_06 or SPI MOSI
13 CPU DIO1_9 CPU DIO1_9
14 SPI_CLK [1] CPU DIO2_07 or SPI clock
15 5V 5V regulated power input
16 HARD_REBOOT# External reset switch input
17 CPU DIO1_10 CPU DIO1_10
18 GND Ground
19 DIO_19 CPU DIO1_24
20 GND Ground
21 CPU DIO1_11 CPU DIO1_11
22 USB_OTG_P i.MX286 USB OTG data (host mode only)
23 CPU DIO1_12 CPU DIO1_12
24 USB_OTG_M i.MX286 USB OTG data (most mode only)
25 DIO_25 CPU DIO1_25(1.6v)
26 USB_SW_5V Switched USB 5V power

6.5.2 Lower header pin-put (40-pin)

Pin # Name Function
1 DIO_00 CPU DIO1_16
2 3.3V 3.3V Output
3 DIO_01 CPU DIO1_17
4 DIO_02 CPU DIO1_18
5 DIO_03 CPU DIO1_19
6 DIO_04 CPU DIO1_20
7 DIO_05 CPU DIO1_21
8 DIO_06 CPU DIO1_22
9 DIO_07 CPU DIO1_23
10 DIO_08 CPU DIO1_15
11 DIO_09 CPU DIO1_14
12 GND Ground
13 CAN_RX0 CPU DIO0_23 or CAN RX0 / CPU DIO2_21
14 CAN_RX1 CPU DIO0_19 or CAN RX1 / CPU DIO3_02
15 CAN_TX0 CPU DIO0_22 or CAN TX0 / CPU DIO2_20
16 CAN_TX1 CPU DIO0_18 or CAN TX1 / CPU DIO3_03
17 UART3_TXD CPU DIO2_19 or UART3
18 5V 5V regulated power input
19 DIO_15 CPU DIO3_29 or PWM4
20 UART2_RXD CPU DIO2_16 or UART2
21 UART2_TXD CPU DIO2_17 or UART2
22 UART0_TXD CPU DIO3_01 or UART0
23 UART0_RXD CPU DIO3_00 or UART0
24 UART1_RXD CPU DIO3_04 or UART1
25 UART1_TXD CPU DIO3_05 or UART1
26 UART3_RXD CPU DIO2_18 or UART3
27 ADC0 i.MX286 ADC0
28 ADC1 i.MX286 ADC1
29 ADC2 i.MX286 ADC2
30 ADC3 i.MX283 ADC3
31 GND Ground
32 I2S_BIT_CLK CPU DIO3_22 or I2S Clock
33 I2S_TXD CPU DIO3_23 or I2S TXD
34 I2S_FRAME CPU DIO3_21 or I2S Frame
35 I2S_MCLK CPU DIO3_20 or I2S MCLK
36 I2S_RXD CPU DIO3_26 or I2S RXD
37 SPI_MOSI [1] CPU DIO2_06 or SPI MOSI
38 SPI_MISO [1] CPU DIO2_04 or SPI MISO
39 SPI_CS# [1] CPU DIO2_05 or SPI Chip select
40 SPI_CLK [1] CPU DIO2_07 or SPI Clock

6.5.3 Other

Name DIO
GRN_LED# CPU DIO0_28
RED_LED# CPU DIO0_17
EN_ETH_POWER# CPU DIO0_6
EN_USB_5V CPU DIO1_27
EN_CAN# CPU DIO3_30


  1. 1.0 1.1 1.2 1.3 1.4 1.5 1.6 These two SPI ports are electrically connected and are the same interface

Example code for CPU DIO manipulation:

#include <assert.h>
#include <fcntl.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
 
#define DIO_Z 2
volatile unsigned int *pinctl = NULL;
 
/*******************************************************************************
* setdiopin: accepts a DIO register and value to place in that DIO pin.
*   Values can be 0 (low), 1 (high), or 2 (z - high impedance).
*******************************************************************************/
void setdiopin(int bank, int pin, int val)
{
	if(val == 2) {
		pinctl[((0xB00) + (0x10 * bank) + 0x8)/4] = (0x1 << pin);
	} else {
		pinctl[((0x700) + (0x10 * bank) + (0x8 / (val+1)))/4] =
		  (0x1 << pin);
		pinctl[((0xB00) + (0x10 * bank) + 0x4)/4] = (0x1 << pin);
	}	
}
/*******************************************************************************
* getdiopin: accepts a DIO pin number and returns its value.  
*******************************************************************************/
int getdiopin(int bank, int pin)
{
	return (((pinctl[((0x900) + (0x10 * bank))/4]) >> pin) & 0x1);
}
 
/*******************************************************************************
* Main: accept input from the command line and act accordingly.
*******************************************************************************/
int main(int argc, char **argv)
{
	int devmem = 0;
	int pin, bank, reg = 0, muxpin;
	int val;
	int returnedValue;
 
	// Check for invalid command line arguments
	if ((argc > 4) | (argc < 3)) {
		printf("Usage: %s bank pin [0|1|2]>\n", argv[0]);
		return 1;
	}
 
	// We only want to get val if there are more than 3 command line arguments
	if (argc == 3) {
		bank = strtoul(argv[1], NULL, 0);
		pin = strtoul(argv[2], NULL, 0);
		val = 0;
	}
	else {
		bank = strtoul(argv[1], NULL, 0);
		pin = strtoul(argv[2], NULL, 0);
		val = strtoul(argv[3], NULL, 0);
	}
 
	assert(bank >= 0 && bank < 5);
	assert(pin >= 0 && pin < 32);
	assert(val >=0 && val < 3);
 
	devmem = open("/dev/mem", O_RDWR|O_SYNC);
	pinctl = mmap(0, getpagesize(), PROT_READ|PROT_WRITE, MAP_SHARED, devmem, 0x80018000);
 
	/* We determine what muxsel reg we need, and set the right pin to DIO*/
	if(pin > 15) {
		reg = 1;
		muxpin = pin - 16;
	} else muxpin = pin; 
	pinctl[((0x100) + (0x20 * bank) + (0x10 * reg) + 0x4)/4] = (0x3 << (muxpin * 2));
 
	// Parse through the command line arguments, check for valid inputs, and exec
	if (argc == 3) {
		returnedValue = getdiopin(bank, pin);
		printf("dio_%d_%d=%d\n", bank, pin, returnedValue);
	} else if(argc == 4) {
		setdiopin(bank, pin, val);
	}
	return 0;
}

tsctl can also be used to manipulate the DIO of the TS-7400_V2, a tarball of libtsctl can be found here. See the tsctl page for more information.

6.6 External Reset

The TS-7670 has a multi-purpose tactile button at a right angle to the PCB. This button can be used as a mechanism to issue a hardware reset to the SBC or as a way to wake up the device from its sleep modes (see Sleep for more information). The stock image for both SD and NAND enable the button to be a reset switch. This functionality can be disabled with:

tshwctl --resetswitchoff

And can be re-enabled with:

tshwctl --resetswitchon

6.7 I2C

A standard two-wire I2C interface is provided on this SBC. The i.MX28 CPU has I2C hardware to communicate with devices on the bus. The hardware is able to be accessed from userspace with the linux i2c-dev interface. On this SBC the I2C pins from the CPU are connected to the on-board RTC, and then brought out to external pins. See the External Interfaces section for the location of these signals.

The RTC on the SBC uses two different addresses, one for the actual RTC registers, the other for the RTC's onboard NVRAM.

Address Function
0x6F RTC
0x57 NVRAM

Outside of those addresses, no other I2C addresses are in use on this SBC.

For more information on the i.MX28 I2C implementation, see the CPU manual.

6.8 Interrupts

We include a userspace IRQ patch in our kernels. This allows you to receive interrupts from your applications where you would normally have to write a kernel driver. This works by creating a file for each interrupt in '/proc/irq/<irqnum>/irq'. The new irq file allows you to block on a read on the file until an interrupt fires.

The original patch is documented here.


The <irqnum> is calculated with the following formula: (((bank * 32) + pin) + 128) Where bank and pin are the DIO number in the bank_pin format. For example, CPU DIO 1_16 (pin 1 of the 40 pin header): (((1 * 32) + 16) + 128) = 176


The Linux kernel supports 3 IRQs from the FPGA. Because of the nature of the NBUS, this requires three separate lines from the FPGA to the CPU. Currently only two IRQs are used from the CPU, one for XUARTS and one for EVGPIO. The third IRQ is not hooked up by default. Any of the IRQs can be repurposed by customization of the FPGA. At any time, the FPGA can toggle the interrupt line, however in order for the kernel to respond to it, the IRQ must be opened first.


CPU IRQ # Name
155 XUART IRQ (not used by xuartctl --server by default)
145 EVGPIO IRQ
228 Unused

This example below will work with any of our TS-Socket boards running Linux. This opens the IRQ number specified in the first argument and prints when it detects an IRQ.

#include <stdio.h>
#include <fcntl.h>
#include <sys/select.h>
#include <sys/stat.h>
#include <unistd.h>
 
int main(int argc, char **argv)
{
	char proc_irq[32];
	int ret, irqfd = 0;
	int buf; // Holds irq junk data
	fd_set fds;
 
	if(argc < 2) {
		printf("Usage: %s <irq number>\n", argv[0]);
		return 1;
	}
 
	snprintf(proc_irq, sizeof(proc_irq), "/proc/irq/%d/irq", atoi(argv[1]));
	irqfd = open(proc_irq, O_RDONLY| O_NONBLOCK, S_IREAD);
 
	if(irqfd == -1) {
		printf("Could not open IRQ %s\n", argv[1]);
		return 1;
	}
 
	while(1) {
		FD_SET(irqfd, &fds); //add the fd to the set
		// See if the IRQ has any data available to read
		ret = select(irqfd + 1, &fds, NULL, NULL, NULL);
 
		if(FD_ISSET(irqfd, &fds))
		{
			FD_CLR(irqfd, &fds);  //Remove the filedes from set
			printf("IRQ detected\n");
 
			// Clear the junk data in the IRQ file
			read(irqfd, &buf, sizeof(buf));
		}
 
		//Sleep, or do any other processing here
		usleep(10000);
	}
 
	return 0;
}


6.9 LEDs

On all of our SBCs we include 2 indicator LEDs which are under software control. You can manipulate these using "tshwctl --greenledon --redledon" or "tshwctl --greenledoff --redledoff". The LEDs have 4 behaviors from default software.

Green Behavior Red behavior Meaning
Solid On Off System is booted and running
Solid On On for approximately 15s, then off Once the system has booted the kernel and executed the startup script, it will check for a USB device and then determine if it is a mass storage device. This is used for updates/blasting through USB. Once it determines this is not a mass storage device the red LED will turn back off.
On for 10s, off for 100ms, and repeating Turns on after Green turns off for 300ms, and then turns off for 10s 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 tshwctl once a valid boot media has started. See the #Watchdog section for more details.
Off Off The SBC is not able to boot. Typically either the board is not being supplied with enough voltage, or the SBC has been otherwise damaged. If a stable voltage is being provided and the supply is capable of providing at least 1A to the SBC, an RMA is suggested.
Blinking about 5ms on, about 10ms off. Blinking about 5ms on, about 10ms off. The board is receiving too little power, or something is drawing too much current from the macrocontroller's power rails.

6.10 NAND

The NAND on the i.MX286 is a 2GiB part attached directly to the CPU. The kernel handles the NAND through its MTD drivers.

Instead of a traditional flash filesystem (JFFS2 for example) the i.MX286 implements UBI and UBIFS.

6.10.1 UBI and UBIFS

UBI is the Unsorted Block Images layer, and is an erase block management layer. UBI serves two purposes, tracking NAND bad blocks and providing wear leveling. While it is possible to run a traditional flash filesystem on top of UBI, it is not recommended. UBIFS was written with UBI in mind and is able to take full advantage of what UBI provides. UBIFS has multiple advantages over JFFS2, UBIFS supports write caching, UBIFS performs better on larger NAND devices, mounts faster, allows for quicker access to large files, improved write speeds, and indexes stored in flash not in system memory.

6.10.2 Using UBI and UBIFS

UBI is implemented directly on top of linux's MTD subsystem, the first thing necessary is to format the device for UBI to use.

ubiformat /dev/mtd1 #This will prepare /dev/mtd1 to accept UBI and is mindful of UBIs erase counters

After this, the device must be attached to UBI

ubiattach -m 1

This will attach the device to the UBI subsystem. Doing this will create a /dev/ubi0 device node that represents the entire UBI device. A UBI attach does take longer on larger MTD devices.

Once this is done, at least one volume must be made. There are two types of volumes, static and dynamic. A dynamic volume is liken to a standard filesystem, it creates and uses a UBIFS filesystem. A static volume is meant to be run right on top of UBI, and does not use UBIFS. It is meant for smaller volumes with blobs of configuration data, and is protected with CRC32s. While it is possible, it is not wise to use UBIFS on top of a static volume, it will result in a much slower device since since both UBI and UBIFS will be implementing CRC32s.

6.11 SD

The i.MX28 SD card controller is used for both SD cards 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 2 partitions:

Device Contents
/dev/mmcblk0 SD Card block device
/dev/mmcblk0p1 Kernel and initramfs
/dev/mmcblk0p2 Full Debian linux partition

6.12 Sleep

The addition of a microcontroller on board this SBC allows it to play a supervisory role over the CPU. Two sleep modes are available, each with the ability to wake up after a set amount of time, or after a push of the tactile push switch on the edge of the PCB.

6.12.1 Sleep

This 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 9mW 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. Note that as soon as the command to sleep is issued, the device will sleep as soon as possible. This has the ability to cause filesystem corruption if proper precautions are not taken before the SBC is put to sleep. In order to enter this mode, issue the following command:

tshwctl --sleep --timewkup <time in seconds> --resetswitchwkup


Note that both --timewkup and --resetswitchwkup are optional arguments, you can pass none, one, or both. If no arguments are passed then the SBC will remain in sleep mode forever, until power is removed completely and re-applied. This can be useful instead of halting in linux as sleeping would consume far less power than simply halting the CPU. Waking up from this mode will take roughly 4-5s from when the timer expires or when the reset button is pressed. This is normal bootup time for the CPU.


6.12.2 Standby

This sleep mode does consume more power, roughly 250mW, however the CPU is put in a standby mode with the RAM contents and CPU cache preserved. When the CPU wakes up from this mode it will continue execution from where it left off. This wakeup process takes roughly 250ms from when the sleep timer expires or the reset button is pushed. Like the sleep mode above, the timer on standby can be an arbitrary number (up to 1847297s, which is 21d 9h 8m 17s) with a 1s resolution. Unlike the above sleep mode, it is safe to enter standby at almost any time without concern for data loss. The only unsafe time is during a write to the SD card that has completed in linux, but the SD card controller is still attempting to flush the write to disk. In all of Technologic Systems' testing, we have not observed any corruption caused by entering or exiting the standby mode. The standby mode can be entered with the following command:

tshwctl --standby --timewkup <time in seconds> --resetswitchwkup


Note that both --timewkup and --resetswitchwkup are optional arguments, you can pass none, one, or both. If no arguments are passed then the SBC will remain in standby mode forever, until power is removed completely and re-applied. In the case of the standby mode however, it does not make sense to leave it in this mode indefinitely. After this mode is exited, the function of the reset switch is restored to its previous state, see External Reset for more information.

6.13 SPI

Note: As of the March 16th 2015 image, TS-7400-V2 Rev B does not correctly support SPI. A fix has been pushed to the github, see Compile the Kernel for more information. This will be corrected in the next image release.

The TS-7400-V2 uses spidev as a method to access SPI devices from userspace. The clock, data, and single chip select line are all directly controlled by the kernel interface. Additional chip selects can be added by utilizing a GPIO pin. See the DIO section for more information on pinouts.

The SPI port will appear as /dev/spidev1.0, standard open(), read(), and write() calls will work on simple devices. SPI devices that require more complex signaling will require the use of various ioctl()s in order to communicate properly. See the linux documentation on SPI and spidev for more information.


6.14 UARTs

The TS-7400_V2 uses 4 CPU UARTs, two brought out at TTL logic levels on the pin headers.

The default software image for the TS-7400-V2 has the i.MX286 UART driver as a module, it must be loaded with the following command before the UARTs can be used:

modprobe mxs_auart

This will then spawn the ttySP* devices in the /dev/ folder


Name Type TX RX CTS RTS
ttySP0 TTL/RS-232 L22/HD3_3 [1] L23/HD3_2 [1] N/A N/A
ttySP1 TTL/RS-232 L25/HD3_7 [1] L24/HD3_8 [1] N/A N/A
ttySP2 TTL L21 L20 N/A N/A
ttySP3 TTL L17 L26 N/A N/A
  1. 1.0 1.1 1.2 1.3 If the RS-232 option is present (U8 installed) it is not advised to use the TTL variant of this UART as the RS-232 transceiver will be driving the lines

6.15 Watchdog

By default there is a /dev/watchdog with the tshwctl daemon running at the highest possible priority to feed the watchdog. This is a pipe that is created in userspace, so for many applications this may provide enough functionality for the watchdog by verifying that userspace is still executing applications. If you would like to have the watchdog functionality more tightly integrated with your application you can specify various feed options.

The watchdog is implemented in the microcontroller that is on this SBC alongside the CPU. This means that a completely separate device is responsible for the sanity of the CPU. The WDT has 100ms resolution, and can be fed for a length of time up to 6553.5s, which is 1h 49m 13s 500ms. Writing a 0, 1, 2, or 3 to the WDT has a special meaning that corresponds with our traditional WDT feed scheme:

Value Result
0 feed watchdog for .3s
1 feed watchdog for 2.7s
2 feed watchdog for 10.8s
3 disable watchdog

The watchdog is armed by default for 10s for the operating system to take over, after which the startup scripts autofeed the watchdog with:

echo a2 > /dev/watchdog

The /dev/watchdog fifo accepts 3 types of commands:

Value Function
f<3 digits> One time feed for a specified amount of time which uses the 3 digit number / 10. For example, "f456" would feed for 45.6 seconds.
"0", "1", "2", "3" One time feed with the value in the above table.
a<num 0-3> This value autofeeds with the value in the above table.

Most applications should use the f<3 digits> option to more tightly integrate this to their application. For example:

#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
 
void do_some_work(int data) {
	/* The contract for sleep(int n) is that it will sleep for at least n
	 * seconds, but not less.  If other kernel threads or processes require
	 * more time sleep can take longer, but when your process has a high
	 * priority this is usually measured in millseconds */
	sleep(5);
}
 
int read_some_io() {
	/* If this function (or do_some_work) misbehave and stall thee watchdog 
         * will not be fed in the main loop and cause a reboot.  You can test 
         * this by uncommenting the next line to force an infinite loop */
	// while (1) {}
	return 42;
}
 
int main(int argc, char **argv)
{
	int wdfd;
	/* In languages other than C/C++ this is still essentially the same, but
	 * make sure you are opening the watchdog file synchronously so the writes
	 * happen immediately.  Many languages will buffer writes together to make 
	 * them more efficient, but the watchdog needs the writes to be timed 
	 * precisely */
	wdfd = open("/dev/watchdog", O_SYNC|O_RDWR);
 
	while (1) {
		int data;
		/* This loop is expected to take about 5-6 seconds, but to allow some
		 * headroom for other applications, I will feed the watchdog for 10s. */
		write(wdfd, "f100", 4);
 
		data = read_some_io();
		do_some_work(data);
	}
}

7 Revisions and Changes

7.1 M0 Microcontroller Changelog

Revision Changelog
0
  • Initial release
1
  • Bugfix where ADC was being overdriven, resulting in improper results

7.2 PCB Revisions

Revision Changelog
A
  • Initial release
B
  • Change from NAND to eMMC for on-board flash.

7.3 Software Images

Image File Changelog Known Issues
ts7670_7400v2-dec032013.dd.bz2
  • Initial release
ts7670_7400v2-jan282014.dd.bz2

ts7670_7400v2-jan282014.ubifs

  • Synced Debian filesystem between TS-7600/TS-4600 and TS-7670/TS-7400_V2
  • Updates to support Rev A TS-7670
  • Fixed fsck issue when booting from NAND
  • Added DoubleStore support
  • Sleep and standby support added
  • tshwctl -i now indicates reboot_source= to indicate what caused the last boot
ts7670_7400v2-mar052014.dd.bz2

ts7670_7400v2-mar052014.ubifs

  • TS-7670 turn on all four LEDs at startup for visual diagnostic purposes
  • Set up routines to control TS-7670 Auto-485 txen
  • Fixed a bug which could cause filesystem_from_* commands to hang
  • Changed NAND sizes to accommodate for maximum factory badblocks
  • /etc/resolv.conf is a static file in Debian, breaks DNS in Debian if IP obtained in initramfs, and then booted to full Debian.
ts7670_7400v2-may302014.dd.bz2

ts7670_7400v2-may302014.ubifs

  • Removed rootwait of SD card, we wait for it in initramfs
  • Support for dblstorctl
  • Updates to tshwctl
    • Include CPU ADC read routines
    • Changed mux to make sure USB ID pin stays in place
    • Implement Marvell's workaround for errata 3.1 for 10mbps connections on 4 port switch
    • Added revision output to 7670/7400_V2
    • Added help output for resetswitch* for all mx28s
    • Renamed 232en and 232dis to *on and *off, old long opt still valid
  • Updates to xuartctl
    • Default to mx28 IRQ when no --irq option is passed
  • Added CFG_CONSOLE_EN option to disable main serial console for security reasons
    • Process running in its place cannot be killed over the console
  • Slightly reorganized the init in order to accommodate the added option
  • Added printing of total RAM available upon bootup
  • Added CFG_DBLSTOR_ROOT config option to allow for making a DoubleStore dataset the Debian root, only when booted from NAND
  • Changed 7670/7400_v2 to turn on CAN and 232 transcievers by default
  • Changed shinit to print boot device
  • Disabled ipv4ll for default case, only used as fallback
  • Removed ethX:0 notation
  • 4th CPU ADC channel not being read properly
ts7670_7400v2-jun272014.dd.bz2

ts7670_7400v2-jun272014.ubifs

  • Added support for 4th CPU ADC channel
  • tshwctl has issue that can corrupt I2C bus cycles if tshwctl is called repeatedly
ts7670_7400v2-jul292014.dd.bz2

ts7670_7400v2-jul292014.ubifs

  • Updated I2C to use i2cdev
  • Fixed bug that can corrupt I2C bus cycles if tshwctl is called repeatedly
  • Redundant "rtc_present=" output removed from tshwctl RTC commands
ts7670_7400v2-jan212015.dd.bz2

ts7670_7400v2-jan212015.ubifs

  • Added support for TS-7680
  • Updated compat-drivers for wireless support, no longer using older compat-wireless
  • Set up SPI on TS-7400-V2
  • Cleaned up GPIO warnings in kernel logs
  • Auto-loading mxs_auart and flexcan
  • Fixed tshwctl bug where a used variable is not initialized in some situations for --get/set/clrdio
  • Forced ordering of SD/MMC in the block driver layer
  • Extra user account support/support exists on the system and may pose a security risk.
  • Kernel SPI drivers do not function on TS-7400-V2 Rev B PCBs
ts7670_7400v2-mar162015.dd.bz2

ts7670_7400v2-mar162015.ubifs

ts7670_7400v2-debian-wheezy-arm-mar162015.tar.bz2

  • Removed call to xuartctl --server which has a very rare chance (1 in 10k as seen in testing) of locking up or causing instability.
  • Added line to give init script a defined stdin/stdout/stderr
  • Added default "unknown" to boardID output
  • Added VLAN support to config for TS-7680
  • Extra user account support/support has been removed
  • Kernel SPI drivers do not function on TS-7400-V2 Rev B PCBs
  • Shutdown does not sync system time to RTC. Before shutdown run the command 'tshwctl --setrtc' to sync the time.
  • Added verbosity in the initramfs will produce some benign messages on bootup, these messages are:
    • "sh: you must specify whom to kill" when booting directly to Debian from SD/NAND/eMMC
    • All of the following messages when booting from NAND:
 "UBI device number 0, total 40 LEBs (20643840 bytes, 19.7 MiB), available 1 LEBs (51609)"
 "mount: mounting /mnt/root/etc on /etc/ failed: No such file or directory"
 "umount: can't umount /etc: Invalid argument"
 "UBI device number 1, total 4015 LEBs (2072125440 bytes, 1.9 GiB), available 110 LEBs)"

8 Product Notes

8.1 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.

8.2 Limited Warranty

Technologic Systems warrants this product to be free of defects in material and workmanship for a period of one year from date of purchase. During this warranty period Technologic Systems will repair or replace the defective unit in accordance with the following process:

A copy of the original invoice must be included when returning the defective unit to Technologic Systems, Inc. This limited warranty does not cover damages resulting from lightning or other power surges, misuse, abuse, abnormal conditions of operation, or attempts to alter or modify the function of the product.

This warranty is limited to the repair or replacement of the defective unit. In no event shall Technologic Systems be liable or responsible for any loss or damages, including but not limited to any lost profits, incidental or consequential damages, loss of business, or anticipatory profits arising from the use or inability to use this product.

Repairs made after the expiration of the warranty period are subject to a repair charge and the cost of return shipping. Please, contact Technologic Systems to arrange for any repair service and to obtain repair charge information.

WARNING: Writing ANY of the i.MX28'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.