Overview

TS-4900
	TS-4900 Product Page
	Product Images
	Specifications
Documentation
	Schematic
	Mechanical Drawing
	FTP Path
Processor
	NXP i.MX6 Quad core, or Solo Arm® Cortex®-A9
	i.MX6 Quad Product Page
	i.MX6 Solo Product Page
	IMX6Q Reference Manual
	IMX6S Reference Manual

The TS-4900 is a TS-Socket System-on-Module (SoM) designed for high performance applications.

Getting Started

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

Debian.org

Virtualization

Suggested Linux Distributions

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

Booting up the board

WARNING:

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

If you are using one of our off the shelf baseboards you will need to refer to that baseboard's manual here. Different baseboards use different power connectors, voltage ranges, and may have different power requirements.

The System-on-Module (SoM) only requires a 5V rail from the baseboard which may be regulated from other voltage ranges. Refer to the #TS-Socket Connector section for the POWER pins. The TS-4900 draws from 0.85W to 6W depending on how idle the processor is, and if you are using a solo, dual, or quad core. A typical power supply for just the SoM will allow around 1.5 A @ 5 V, but a larger power supply may be needed depending on your peripherals.

Once you have applied power to your baseboard you should look for console output. The next section of the manual provides information on getting the console connected. The first output is from U-Boot:

U-Boot 2013.10-00049-g311750c (Jul 10 2014 - 10:37:04)

CPU:   Freescale i.MX6Q rev1.2 at 792 MHz
Reset cause: POR
Board: TS-4900
DRAM:  2 GiB
MMC:   FSL_SDHC: 0, FSL_SDHC: 1
SF: Detected N25Q64 with page size 256 Bytes, erase size 4 KiB, total 8 MiB
*** Warning - bad CRC, using default environment

In:    serial
Out:   serial
Err:   serial
Net:   using phy at 7
FEC [PRIME]
Hit any key to stop autoboot:  0

The default U-Boot will check for USB updates, and then will check the "SD Boot" jumper. If the SD boot jumper is set, it will boot to the Linux on the SD card. If it is not set, it will boot to the eMMC.

Note:

The "*** Warning - bad CRC, using default environment" can be safely ignored. If you "env save" this will use your environment on the disk, but on new boards the SPI flash is erased so it just doesn't have a modifed env saved.

Get a Console

The console UART (ttymxc0) is a TTL UART at 115200 baud, 8n1 (8 data bits 1 stop bit), and no flow control. On the System-on-Module this is CN2_93 (TX), CN2_95 (RX). Various baseboards bring this out using different methods. The TS-8550 baseboard brings out a DB9 connector with the console as RS232. Other baseboards have a jumper to switch between the console port and another serial port. Some baseboards require an adapter board like the TS-9449. Refer to the baseboard model you are using [Main_Page#Baseboards|here]] for more information on any specific jumpers or ports to connect to for console.

Console from Linux

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

picocom is a very small and simple client.

sudo picocom -b 115200 /dev/ttyUSB0

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

sudo screen /dev/ttyUSB0 115200

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

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

U-Boot

The TS-4900 includes u-boot as the bootloader to launch the full operating system. When the i.MX6 processor starts it loads u-boot from the onboard 8MB SPI flash. This allows you to include your boot image on either the SD, eMMC, SATA, NFS, or USB. U-boot is a general purpose bootloader that is capable of booting into common Linux distributions, Android, QNX, or others.

On a normal boot you should see something similar to this:

U-Boot 2013.10-00034-ga8a4e60 (May 02 2014 - 12:19:18)

CPU:   Freescale i.MX6Q rev1.2 at 792 MHz
Reset cause: POR
Board: TS-4900
DRAM:  2 GiB
MMC:   FSL_SDHC: 0, FSL_SDHC: 1
SF: Detected N25Q64 with page size 256 Bytes, erase size 4 KiB, total 8 MiB
In:    serial
Out:   serial
Err:   serial
Net:   using phy at 7
FEC [PRIME]
Hit any key to stop autoboot:  5

By default the board will boot to SD or eMMC depending on the status of CN1_98/MODE2 on startup. On our off the shelf baseboards this pin is brought out as the "SD Boot" jumper. This can be customized further in u-boot as described below.

U-Boot Environment

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

# Print all environment variables
env print -a

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

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

# Execute commands saved in a variable
env run hellocmd;

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

# Restore environment to default
env default -a

# Remove a variable
env delete emmcboot

U-Boot Commands

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Test memory.
mtest

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

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

# Test ICMP
dhcp
ping 192.168.0.11

# Reboot
reset

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

# Delay in seconds
sleep 10

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

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

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

# Print U-Boot version/build information
version

Modify Linux Kernel cmdline

The Linux kernel cmdline can be customized by modifying the cmdline_append variable. The variable contents are clobbered when set, so be sure to specify the full desired cmdline string.

env set cmdline_append console=ttymxc0,115200 init=/sbin/init quiet
env save

The kernel command line can also be modified from from the on-board Linux. Debian (and other distributions) provide a U-Boot utilities package that contains the tools necessary to create a U-Boot script:

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

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

Booting From NFS

U-Boot's NFS support can be used to load a kernel, device tree binary, and root filesystem. The default scripts include an example NFS boot script.

# Set this to your NFS server ip
env set serverip 192.168.0.11;

# Set this to your NFS root path.  The server root should be accessible at this path.
env set nfsroot /path/to/nfs/rootfs/
env save

To boot your NFS root:

# Boot to NFS once
run nfsboot;

# To make the NFS boot the persistent default
env set bootcmd run nfsboot;
env save

Booting From USB

Our U-Boot by default will attempt to read a U-Boot script named /tsinit.ub from a USB drive on bootup. If present on the USB drive, U-Boot will automatically load this script in to memory and execute it. For our bootable USB disk images, no further action is needed.

To make a bootable drive from scratch, create a single ext3 partition on a USB drive and copy over your preferred rootfs just like you would with an SD card. This is described in the Debian and Yocto sections.

The one addition is to create the /tsinit.ub file in the root of the USB drive in order to allow U-Boot to boot from the drive's contents.

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

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

# DO NOT MANUALLY EDIT THE .UB FILE

# If loading files from a partition other than the first partition on disk, change
# the second number to the partition number
env set bootpart 0:1

if test ${model} = '4900';
	then load usb 0:1 ${loadaddr} /boot/ts4900-fpga.bin;
	ice40 ${loadaddr} ${filesize};

	bbdetect;

	# Check rev, attempt to load the best dtb file for compatibility. If Rev E files
	# are not found, attempt to boot prior dtb. If not Rev E, just boot prior dtb.
	if test ${rev} > 'D'; then
		if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-reve-${baseboardid}.dtb
			then echo Baseboard $baseboardid detected;
		elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-reve.dtb
			then echo Booting default Rev E device tree;
		elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb
			then echo Baseboard $baseboardid detected;
		elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb
			then echo Booting default device tree;
		fi
	else
		if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb
			then echo Baseboard $baseboardid detected;
		elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb
			then echo Booting default device tree;
		fi
	fi

	load usb ${bootpart} ${loadaddr} ${uimage};
	setenv bootargs root=/dev/sda1 rootwait rw ${cmdline_append};
	bootm ${loadaddr} - ${fdtaddr};

elif test ${model} = '7970'; then
	# Check for Rev F or newer. If so, load that dtb. If Rev F dtb does not exist
	# fall back to a prior dtb. If earlier Rev PCB, use prior dtb.
	if test ${rev} > 'E'; then
		if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970-revf.dtb; then
			echo Loaded TS-7970 Rev F device tree;
		elif load usb ${bootdev} ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970.dtb; then
			echo Loaded TS-7970 device tree;
		fi
	else
		if load usb ${bootdev} ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970.dtb; then
			echo Loaded TS-7970 device tree;
		fi
	fi

	load usb 0:1 ${loadaddr} ${uimage};
	setenv bootargs root=/dev/sda1 rootwait rw ${cmdline_append};
	bootm ${loadaddr} - ${fdtaddr};
fi

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

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

You may need to install u-boot-tools or the equivalent package for your distribution.

Update U-Boot

WARNING:

Installing your own u-boot is not recommended and may cause the board to fail to boot.

U-boot requires a different build for Quad/Dual and Solo/Duallite. Flashing the wrong u-boot will cause the board to fail to properly boot. Recovery in this case would require a TS-8550, or submitting an RMA.

On your current u-boot, type "env print imx_type" and this will return the u-boot build you should use. Copy the u-boot.imx to the SD card, and run:

mmc dev 0
load mmc 0:1 ${loadaddr} /u-boot.imx
sf probe
sf erase 0 0x80000
sf write ${loadaddr} 0x400 $filesize

U-boot Recovery

We have several variations of the TS-4900's u-boot which include different RAM configurations for the Quad core, solo commercial, solo industrial, and a few older variants. On a functional board if you run "ech o ${imx_type}" this will show which variant you are running. To recover the system you must get it booting over the USB OTG port.

Boot the TS-4900 on a TS-8550 carrier board and flip the Boot select switch up. This will boot to the TS-8550 SPI flash which includes a blank flash. If the CPU boots up and the internal ROM does not find a valid header on the boot device, it will fall back to the "Serial Downloader". If it is in this mode and the USB1 header on the TS-8550 is connected to your Linux pc you will see this in dmesg:

 hid-generic 0003:15A2:0054.0006: hiddev0,hidraw3: USB HID v1.10 Device [Freescale SemiConductor Inc  SE Blank ARIK] on usb-0000:00:14.0-6.4.2/input0

If this does not show up then the SPI flash may have a valid image programmed, though it is not capable of booting the system. In this case the CPU must be strapped to force this USB serial downloader boot. On Boot:

Name	Location	Value
BOOT_MODE_0	CN1_52	1
BOOT_MODE_1	CN2_54	0

Normally these BOOT_MODE[1:0] pins are strapped to "10" for Internal boot, so both of these will need to be jumpered with wires to 3.3v/GND to force a serial downloader boot.

Once it is in this mode you can use the imx USB loader to boot the board.

IMX USB loader

After building imx_usb on your host pc, run "imx_usb u-boot.imx" to get u-boot loaded and running on the cpu. You can then use the instructions #Update u-boot to get the system permanently booting again.

Alternatively, if the u-boot is erased and you need it recovered you can submit an RMA for us to recover the board.

U-boot Development

We do provide our u-boot sources, but we do not recommend rebuilding a custom uboot if it can be avoided. This CPU has a long lifetime which will outlast most RAM chips. If we have to update the RAM timing later in the boards life due to an EOL, die change, or any other change that may require new RAM configuration/timing changes, we will update this in our shipping u-boot. If you are using our u-boot these changes will happen without affecting your application. If you are using a custom u-boot you may need to rebuild to get the updated settings.

Our u-boot includes a variable "imx_type". If you are loading a custom u-boot, make sure you check the value of this before writing. If we are forced to update the RAM configuration we will change this variable. We will also send out a product change to anyone who is subscribed to our PCS system.

If you still want to proceed with building a custom u-boot, use the master branch from the github here: https://github.com/embeddedTS/u-boot

Boot up a TS-4900 into u-boot and run "echo ${imx_type}". This will show you the u-boot config to use for the correct RAM timing. We use the same GCC 4.8 used from yocto Fido to compile the u-boot binary.

Download the toolchain here.

source /opt/poky/1.8/environment-setup-cortexa9hf-vfp-neon-poky-linux-gnueabi

# For example, one of the quad core variants.  Replace this with your imx_type
make ts4900-q-2g-1000mhz-c_defconfig
make -j4

This will output a u-boot.imx you can write to the board using the steps in #Update_U-Boot.

Fallback Capable U-boot scripts

U-boot can be configured to have a fallback boot if your application does not acknowledge a successful boot. These scripts can be used in place of the defaults which will require your application to acknowledge a successful boot. If the system returns to u-boot again indicating a failed boot, it will instead boot to the fallback script. The fallback script could be booting to sd, a different read only partition on eMMC, or a small kernel/initramfs on the SPI flash.

env set bootcmd 'sf probe; sf read ${loadaddr} 80000 1; mw.b ${fdtaddr} 0xf0 1; if cmp.b ${loadaddr} ${fdtaddr} 1; 
then run fallback; else sf erase 80000 1000; sf write ${fdtaddr} 80000 1; run emmcboot; fi;';
env set fallback 'run usbprod; sf probe; echo set your fallback action here';
sf erase 80000 1000;

env set sdboot 'echo Booting from the SD; if load mmc 0:1 ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb; 
then echo $baseboardid detected; else echo Booting default device tree; 
load mmc 0:1 ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb;
 fi; if fdt addr ${fdtaddr}; then echo "Loaded Device Tree"; else run fallback; fi; 
if load mmc 0:1 ${loadaddr} /boot/ts4900-fpga.bin; then echo "Loaded FPGA"; else run fallback; fi; 
if load mmc 0:1 ${loadaddr} ${uimage}; then echo "Loaded Kernel"; else run fallback; fi; 
setenv bootargs root=/dev/mmcblk1p1 rootwait rw ${cmdline_append}; bootm ${loadaddr} - ${fdtaddr}; 
run fallback;'

env set emmcboot 'echo Booting from the eMMC; if load mmc 1:1 ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb; 
then echo $baseboardid detected; else echo Booting default device tree; load mmc 1:1 ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb;
 fi; if fdt addr ${fdtaddr}; then echo "Loaded Device Tree"; else run fallback; fi; 
if load mmc 1:1 ${loadaddr} /boot/ts4900-fpga.bin; then echo "Loaded FPGA"; else run fallback; fi; 
if load mmc 1:1 ${loadaddr} ${uimage}; then echo "Loaded Kernel"; else run fallback; fi; 
setenv bootargs root=/dev/mmcblk2p1 rootwait rw ${cmdline_append}; bootm ${loadaddr} - ${fdtaddr}; run fallback;'

env save;

Once your application has started you can clear the error byte to indicate a successful boot with:

dd if=/dev/zero bs=1 of=/dev/mtdblock0 seek=524288 count=1

Access U-boot Environment from Linux

U-Boot includes a utility fw_printenv which set set/read environment variables from Linux. This must be built and provided with a config file before it will work.

On the board first boot to u-boot by pressing ctrl+c on startup. At the prompt run:

U-Boot > env print imx_type
imx_type=ts4900-s-1g-800mhz-i

Save this output then boot to Linux to build the fw_printenv tool.

cd /usr/src/
git clone --depth 1 https://github.com/embeddedTS/u-boot-imx.git -b imx_v2015.04_3.14.52_1.1.0_ga
cd u-boot-imx

Since u-boot gave us "imx_type=ts4900-s-1g-800mhz-i", the example defconfig is ts4900-s-1g-800mhz-i_defconfig. Your board's defconfig may be different and this build should match.

make ts4900-s-1g-800mhz-i_defconfig
make -j4 env
cp tools/env/fw_printenv /usr/bin/
# The same utility sets environment variables when
# called as fw_setenv
ln -s /usr/bin/fw_printenv /usr/bin/fw_setenv

The board will also need a config file to know where to load the environment. Create a file /etc/fw_env.config

# SPI flash on the TS-4900
# MTD device name	Device offset	Env. size	Flash sector size	Number of sectors
/dev/mtdblock1		0x0		0x2000		0x1000			2

From here you can run "fw_printenv" and read the environment variables. If first line of output is:

Warning: Bad CRC, using default environment

Then the environment is blank, and u-boot is loading the environment compiled into the u-boot binary. This is normal and is how boards are shipped.

You can modify variables with this command as well:

# Set cmdline_append to include "quiet"
fw_setenv cmdline_append console=ttymxc0,115200 ro init=/sbin/init quiet

Buildroot

The full-featured Debian image may be too cumbersome for some applications. Applications that require faster bootup time or a smaller root filesystem will benefit greatly from using a lighter distribution like Buildroot. Using Buildroot for generating images makes it easy to keep software up to date, both userspace and kernel. Additionally, the use of Buildroot allows for building full images completely from source, with semi-reproducable builds, and full software license reports.

To assist customers heading down this path, we maintain our own Buildroot br2-external tree. This tree includes upstream Buildroot as a submodule, which eases updating between Buildroot releases. See the Buildroot manual for more information on Buildroot and br2-external trees.

In order to provide an easy transition from a larger Linux distribution to Buildroot, we provide and maintain two levels of configurations:

The base configuration for each device brings in hardware support to get the unit booted, but offers minimal software support and relies mostly on tools provided by BusyBox.
An "extra packages" defconfig that can be merged in with any of the base configurations in order to provide many additional packages to create an environment that is more consistent with larger Linux distributions.

The larger Buildroot configuration averages about 10 seconds of boot time, much of which is spent on networking. The base configurations can reduce this time significantly.

Our Buildroot br2-external currently uses the linux-5.10.y branch of our Linux LTS kernel repository for the majority of its supported platforms.

Note: Note that our base configurations include that device's utilities package where possible. Normally, these utilities (e.g. tshwctl, tsmicroctl, etc.) list the git hash of the build source in the help output. However, due to the Buildroot process, the git hash in these utilities reflects the git hash of Buildroot-ts, NOT of the utilities repository. There is no way to work around this without building the utilities outside of Buildroot.

Buildroot - Installing

When building Buildroot from source, the output files can be used to create a bootable microSD card and a bootable eMMC for the TS-4900. The output files are also compatible with our USB Image Replicator.

The default configuration was designed to be as close to our stock Debian distribution. This includes our ts4900-utils like tsmicroctl, drivers, firmware, and software for the Wi-Fi and Bluetooth module, etc.

Buildroot - Building

Buildroot is intended to be completely cross-compiled from a host Linux workstation. This process creates a cross-compiler which is then used to build all target applications, kernel, etc., and then output a bootable image / tarball. The following instructions will create a bootable image / tarball for the target system:

Clone the repository:

git clone --recurse-submodules https://github.com/embeddedTS/buildroot-ts.git
cd buildroot-ts/

Configure the build:

# The following command uses a Buildroot script to merge two config files.
# The extra_packages_defconfig includes more usual packages to match our stock images
./buildroot/support/kconfig/merge_config.sh technologic/configs/extra_packages_defconfig technologic/configs/tsimx6_defconfig 

# A smaller base image can be made with bare hardware support using:
# make tsimx6_defconfig

At this point, the default configuration can be modified if desired:

make menuconfig

And finally, start the build process:

make

The Buildroot process can take a large amount of time to build depending on available system resources. Note that if any changes occur in the config file, it is recommended to clean the build tree and start the process over. Buildroot ccache is not enabled by default, but can be to help speed up repeated builds. See the Buildroot manual for more information about ccache and Buildroot.

Once it is finished building, Buildroot will output a filesystem tarball to buildroot/output/images/rootfs.tar.xz. This file can be used with the Installing Buildroot instructions to get this tarball booted on the target device.

Buildroot - Cross Compiling

In order to generate a cross-compiler from Buildroot, first configure the target build as outlined in the first steps of the build instructions. Once configured, a separate make command can be issued to generate a tarball package of the cross-compiler. This can be unpacked to any location on the host Linux workstation's filesystem and then used to cross-compile additional applications for the target. The build, setup, and use of the cross-compiler can be done with the following steps:

# Be sure the target is configured first!
# The following command will output the cross-compiler package as well as build the target image completely if not built already
make sdk

# Unpack the tarball to new directory in the users home directory
# Note that the tarball name may be slightly different depending on how the toolchain is configured in Buildroot
mkdir ~/buildroot-toolchain
tar xf buildroot/output/images/arm-buildroot-linux-gnueabihf_sdk-buildroot.tar.gz -C ~/buildroot-toolchain/

# Update the path information for the toolchain (must be done when the tarball is unpacked, or if the root folder of the toolchain is moved!)
# Note that, as above, the path for the compiler may be slightly different depending on how the toolchain is configured in Buildroot
~/buildroot-toolchain/arm-buildroot-linux-gnueabihf_sdk-buildroot/relocate-sdk.sh

# Create a simple Hello World application source
cat << EOF > hello.c
#include <stdio.h>
void main(void) { printf("Hello!\n"); }
EOF

# Build a binary from the Hello World source that can be run on the target device
~/buildroot-toolchain/arm-buildroot-linux-gnueabihf_sdk-buildroot/bin/arm-linux-gcc hello.c -o hello

# This cross compiler can be added to the user's PATH variable for easy access
export PATH=$PATH:~/buildroot-toolchain/arm-buildroot-linux-gnueabihf_sdk-buildroot/bin
arm-linux-gcc hello.c -o hello

The hello binary can then be copied to the target device and executed on it.

Note that the make sdk command can be run at any time to generate the toolchain tarball. Even after Buildroot has generated the output image.

Buildroot is extremely flexible in its generation and use of a cross-compiler. See the Buildroot manual for more information on advanced use of the Buildroot generated toolchain as well as using Buildroot's generated cross-compiler as an external compiler for Buildroot.

Buildroot - Configuring Network

Buildroot implements the ip, ifconfig, route, etc., commands to manipulate the settings of interfaces. The first Ethernet interface is set up to come up automatically with our default configuration. The interfaces can also be manually set up:

# Bring up the CPU network interface
ifconfig eth0 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 a default route. This is the server that provides an internet connection.
route add default gw 192.168.0.1

# Edit /etc/resolv.conf for the local 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:

# To setup the default CPU Ethernet port
udhcpc -i eth0
# All Ethernet ports can be made active and request DHCP addresses with:
udhcpc

To have network settings take effect on startup in Buildroot, edit /etc/network/interfaces:

# interface file auto-generated by Buildroot

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
  pre-up /etc/network/nfs_check
  wait-delay 15

Note that the default network startup may timeout on some networks, e.g. network protocols such as STP can delay packet movement. This can be resolved in Buildroot by adding network configuration options to fail after a number of attempts (rather than a timeout) or retry for a DHCP lease indefinitely. For example, adding one of the following lines under the iface eth0 inet dhcp section:

udhcpc_opts -t 0 to infinitely retry
udhcpc_opts -t 5 to fail after five attempts.

See the man page for interfaces(5) for further information on the syntax of the interfaces file and all of the options that can be passed.

For more information on network configuration in general, Debian provides a great resource here that can be readily applied to Buildroot in most cases.

Buildroot - Installing New Software

Buildroot does not include a package manager by default (though it is possible to enable one). This means installing software directly on the platform can be cumbersome and is not the intended path when using Buildroot. It is recommended to modify the Buildroot configuration to include additional packages. See the Building Buildroot section for information on modifying the configuration to build additional packages.

If a desired package is not available in Buildroot, there are a number of options available moving forward. It is possible to add packages to the build process, though this does require some knowledge of Buildroot internals. Another option is to use the cross compiler that is output by Buildroot in order to compile packages on a host system and then copy them over to the target. It is also possible to install a toolchain directly on the device, and compile applications natively. The last option is the least recommended as it greatly increases the final image size and adds unnecessary complexity.

Buildroot - Setting Up SSH

The default configuration has Dropbear set up. Dropbear is a lightweight SSH server.

Make sure the device is configured on the network and set a password for the remote user. SSH will not allow remote connections without a password set. The default configuration does not set a password for the root user, nor are any other users configured.

passwd root

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

Buildroot - Starting Automatically

Buildroot defaults to using the BusyBox init system, and all of our provided configurations use this as well. The following custom startup script uses this format. For information on other init systems that Buildroot can use, as well as creating startup scripts for these, see the Buildroot manual.

The most straightforward way to add an application to startup is to create a startup script. This example startup script that will toggle the red LED on during startup, and off during shutdown. In this case the script is named customstartup which can be changed as needed.

Create the file /etc/init.d/S99customstartup with the following contents. Be sure to set the script as executable!

#! /bin/sh
# /etc/init.d/customstartup

case "$1" in
  start)
    echo 1 > /sys/class/leds/red-led/brightness
    ## 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
    echo 0 > /sys/class/leds/red-led/brightness
    ;;
  *)
    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.

Buildroot provides numerous mechanisms to create this file in the target filesystem at build time. See the Buildroot manual for more information on this.

This script will be automatically called at startup and shutdown thanks to the file location and naming. However, it can also be manually started or stopped:

/etc/init.d/S99customstartup start
/etc/init.d/S99customstartup stop

Yocto

Yocto is our recommended distribution for graphics packages as the software includes patches to support the GPU. X11 in Yocto includes drivers for providing 2D support as well. Support is also provided for OpenGLES 1&2, as well as GStreamer acceleration, included standalone or with Qt. Yocto also provides cross toolchains that include the rootfs. This toolchain allows integration with the Qt Creator IDE and Eclipse.

Yocto does not provide binary security updates. This distribution also does not have any remote repository of pre-built applications. For either of these we features we recommend using Debian.

Our current Yocto support is based off of Yocto 3.0 "Zeus".

Getting Started with Yocto

Yocto itself is a set of scripts and tools used to build a custom distribution. In our default images we try to include all the common utilities requested by users. Rebuilding Yocto should not be necessary for many users, but is possible if needed. See the Custom Build Yocto section for information on this process.

Our Yocto rootfs tarball is available here:

Yocto Download Links
Yocto Image	Download Link
ts-x11-image (Yocto Zeus)	Download

To write this to an SD card, first partition the SD card to have one large ext3 partition. Most SD cards include one MBR partition by default. Cards can also be partitioned with fdisk, cfdisk, or the graphical gparted utility. This should be an MBR partition table, not GPT. Once it is partitioned, format the SD and extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -jxf ts-x11-image-tsimx6-latest.rootfs.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

To rewrite the eMMC, boot to the SD card. You cannot rewrite the eMMC while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/yocto/zeus/ts-x11-image-tsimx6-latest.rootfs.tar.bz2 | tar --numeric-owner xj -C /mnt/emmc/
umount /mnt/emmc
sync

The same commands can be used to write SATA by substituting /dev/mmcblk2p1 with /dev/sda1.

First Boot

The stock Yocto image provides a single login of root with no password. With Zeus, the wired ethernet interface will attempt to acquire an IP address via DHCP automatically. However, it is not possible to log in via the network at this time due to security of the device requiring a password for SSH access. Initial login to the device must first be done on the serial console.

Yocto Networking

Our Yocto image uses systemd which stores its network files in /etc/systemd/network/. Yocto will automatically enable DHCP on its wired interfaces. This can be overridden to set a static IP or enable other options for DHCP. The only requirement is that this file is named /etc/systemd/network/XX-wired.network Where "XX" is a number smaller than 80, e.g. /etc/systemd/network/79-wired.network This format must be used for all eth* and en* named network interfaces. The lower file names will take priority.

An example of a static configuration would be:

/etc/systemd/network/42-wired.network

[Match]
Name=eth0

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

DNS will be loaded from /etc/resolv.conf. To make this use a static DNS:

rm /etc/resolv.conf
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 8.8.4.4" >> /etc/resolv.conf

To use the DNS assigned by DHCP, run:

ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

For more information on what options are available to configure the network, see the systemd network documentation.

Yocto Wireless

Yocto uses systemd to start wpa_supplicant, and systemd-networkd to set an IP address via a static setting or DHCP.

Scan for a network

ifconfig wlan0 up

# Scan for available networks
iw wlan0 scan

An example of connecting to an open network with an SSID of "default":

BSS c0:ff:ee:c0:ff:ee(on wlan0)
        TSF: 848750528860 usec (9d, 19:45:50)
        freq: 2462
        beacon interval: 100 TUs
        capability: ESS Privacy ShortPreamble ShortSlotTime RadioMeasure (0x1431)
        signal: -69.00 dBm
        last seen: 3253 ms ago
        Information elements from Probe Response frame:
        SSID: default
        Supported rates: 1.0* 2.0* 5.5* 11.0* 6.0* 9.0 12.0* 18.0 
        DS Parameter set: channel 11
        Country: US     Environment: Indoor/Outdoor
                Channels [1 - 11] @ 30 dBm

To connect to this open network manually for just this boot:

iw wlan0 connect "default"

If connecting using WEP, also specify a network key:

iw wlan0 connect "default" keys 0:abcde d:1:0011223344

If connecting to a WPA network use wpa_passphrase and wpa_supplicant:

mkdir /etc/wpa_supplicant/
wpa_passphrase "ssid name" "full passphrase" >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf

After generating the configuration file the wpa_supplicant daemon can be started.

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

This will return output similar to:

 Successfully initialized wpa_supplicant
 root@ts-imx6-q:~# dmesg
 ...
 [  306.924691] wlan0: authenticate with c0:ff:ee:c0:ff:ee
 [  306.959415] wlan0: send auth to c0:ff:ee:c0:ff:ee (try 1/3)
 [  306.968137] wlan0: authenticated
 [  306.978477] wlan0: associate with c0:ff:ee:c0:ff:ee (try 1/3)
 [  306.988577] wlan0: RX AssocResp from c0:ff:ee:c0:ff:ee (capab=0x1431 status=0 aid=9)
 [  307.009751] wlan0: associated
 [  307.012768] IPv6: ADDRCONF(NETDEV_CHANGE): wlan0: link becomes ready
 [  307.047989] wlcore: Association completed.

Use iw wlan0 info and iw wlan0 station dump to verify the connection. This will also report the link quality to the AP.

Wireless may be associated, but this does not get an IP on the network. To connect to the internet or talk to the internal network first configure the interface. See configuring the network, but on many networks only a DHCP client is needed:

udhcpc -i wlan0

Systemd can also be configured to start wpa_supplicant on boot up.

# Assuming the same path for the wpa conf file as shown above
systemctl enable wpa_supplicant@wlan0
systemctl start wpa_supplicant@wlan0

Once this service is started it will bring up the wlan0 link and associate it to the SSID that is noted in the wpa_supplicant.conf file. Configure the IP settings the same way as a wired network.

In /etc/systemd/network/wlan0.network

[Match]
Name=wlan0

[Network]
DHCP=yes

For a static configuration of IP, the following format may be used:

[Match]
Name=wlan0

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

For more information on what options are available to configure the network, see the systemd network documentation.

Yocto Application Development

Yocto provides a cross toolchain including the native tools and required ARM libraries. The cross toolchain is only available for 64bit Linux host PCs. Download the toolchain by saving the following link:

poky-glibc-x86_64-meta-toolchain-qt5-cortexa9t2hf-neon-tsimx6-toolchain-3.0.2.sh

In order to install the toolchain, use the following commands to run the installation script:

chmod a+x poky-*.sh
sudo ./poky-*.sh

In order to use the toolchain, the environment for it must be sourced to the current terminal before it can be used to build applications: To build an application first source the environment for the toolchain:

source /opt/poky/3.0.2/environment-setup-cortexa9t2hf-neon-poky-linux-gnueabi

# This command sets up paths for the shell along with a number of other
# environment variable. For example:
$ echo $CC
arm-poky-linux-gnueabi-gcc -march=armv7-a -marm -mthumb-interwork -mfloat-abi=hard -mfpu=neon -mtune=cortex-a9 --sysroot=/opt/poky/3.0.2/sysroots/cortexa9hf-vfp-neon-poky-linux-gnueabi

# Cross compiling a simple hello world program:
$CC hello.c -o hello

It is also possible to develop applications directly on the device via serial console or ssh. Yocto includes development tools such as vim, gcc, g++, gdb, make, autoconf, binutils, etc. See the next sections for using the cross toolchain with IDEs.

Configure Qt Creator IDE

Note: This guide is intended for our stock Yocto image using systemd. On custom images, the same instructions should apply if a cross toolchain is built. This can be built through Yocto with bitbake meta-toolchain-qt5. Be sure to update the paths if using a different distribution.

Install the qtcreator tool on a host Linux PC. Any recent version from a modern Linux distribution should be sufficient and work without issue. On a Debian/Ubuntu desktop, run:

sudo apt-get update && sudo apt-get install qtcreator -y

The SDK which includes the Qt support will also need to be downloaded. The cross toolchain is only available for 64-bit Linux host PCs:

poky-glibc-x86_64-meta-toolchain-qt5-cortexa9t2hf-neon-tsimx6-toolchain-3.0.2.sh

In order to install the toolchain, use the following commands to run the installation script:

chmod a+x poky-*.sh
sudo ./poky-*.sh

These instructions assume the installation path will be the default at /opt/poky/3.0.2/

Note:

An environment script has to be sourced before every execution of qtcreator. Without this, builds will fail.

source /opt/poky/3.0.2/environment-setup-cortexa9t2hf-neon-poky-linux-gnueabi
qtcreator

Qt Creator needs to be configured to build using this toolchain. Once Qt Creator is launched, select Tools->Options->Devices Click Add, select Generic Linux Device, and then click Start Wizard

On the next page specify the IP address or hostname of the device running Yocto. In this example, the unit has an IP address of 192.168.2.45 obtained via DHCP. The default Yocto image will use the user root with no password to connect. Set the name to TSIMX6

It will then verify connectivity. Click close and continue.

Note:

The paths given in the images below may not match the latest toolchain, but are meant to show where these values would go. Follow the text appropriate to the architecture of your host PC for the correct values

In the left column of the Options menu, select Build & Run. On the Qt Versions tab, click Add in the upper right to configure the TS Kit. Qt Creator may see the qmake binary added to your path from the sourced environment script. If this is detected, add in the string TSIMX6 to the title as shown in the photo below. If it is not autodetected, add the full path and ensure the version name is set to TSIMX6 Qt 5.13.2. This will allow it to be recognized when setting the right binary for the kit.

/opt/poky/3.0.2/sysroots/x86_64-pokysdk-linux/usr/bin/qmake

On the Compilers tab click Add, select GCC then C. Set the Name to TSIMX6 GCC. For the Compiler Path use the following:

/opt/poky/3.0.2/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gcc

Repeat the above steps for the g++ compiler; click Add, select GCC then C++. Set the name to TSIMX6 G++. And for the Compiler Path use the following:

/opt/poky/3.0.2/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-g++

On the Debuggers tab click Add. For name, specify TSIMX6 GDB. For the path, specify the location of gdb with the following:

/opt/poky/3.0.2/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb

On the Kits tab click Add. For Name, enter TSIMX6. Set device type to Generic Linux Device. Set the device to TSIMX6 (default for Generic Linux). Set Qt mkspec to the following (make sure there is no space at the end):

/opt/poky/3.0.2/sysroots/cortexa9t2hf-neon-poky-linux-gnueabi/usr/lib/mkspecs/linux-oe-g++

Set C Compiler to TSIMX6 GCC and C++ Compiler to TSIMX6 G++. Set Debugger to TSIMX6 GDB. Set the Qt version to TSIMX6 QT 5.13.2. Finally, click Apply.

Note:

If there is a red exclamation point over the kits icon, it indicates that the compiler ABI does not match. In this case, you will need to revisit the "Compiler", "Debugger", and "Qt Versions" tabs, and browse the host PC for these files manually rather than copy/pasting the paths from these instructions. This is a bug in Ubuntu 16.04's Qt Creator, and may be in later versions as well.

At this point Qt Creator is set up to begin a hello world project.

Qt Creator Hello World

Open the Qt Creator IDE and click New Project.

Qt provides multiple templates for application development. For this example select the default Qt Widgets Application.

Specify the location for your project. Keep in mind that the compile process will create more build paths in the Create In: path.

Next, select the kit. The TSIMX6 is the kit we set up in the last section, but you may have other kits pre-installed on your system. These can be used for testing graphical development on your PC. Keep in mind distribution versions may contain different functionality.

Next select the class and filename information. This example will use the defaults.

Select any version control for the project. The example will use none and finish the wizard. This will generate the new project.

Click the button under Help on the left column, and select TSIMX6 debug. If there is only one kit selected, this will be default.

Now return to edit, and open the Qt project file, qt5-helloworld.pro. Add in these lines anywhere after the target is specified:

linux-* {
    target.path = /home/root
    INSTALLS += target
}

Last, the DISPLAY must be selected. This is done by setting a run environment variable that will be set when the application is run on the board.

At this point click the green allow in the bottom left to run the application. This can also be launched from the menu at Build->Run.

From here, you can begin customizing your application. Refer to the official Qt documentation for more information

Qt 5 Documentation

Yocto Hide Cursor

The default image includes the xcursor-transparent icon theme. This can hide the mouse pointer. To enable this, run these commands:

mkdir -p ~/.icons/default/

echo "[Icon Theme]" > ~/.icons/default/index.theme
echo "Inherits=xcursor-transparent" >> ~/.icons/default/index.theme

# Now reset x, or reset the unit and the cursor will be invisible.

Yocto Startup Scripts

To have a custom headless application start up at boot a systemd service needs to be created. Create the file /etc/systemd/system/yourapp.service with contents similar to below:

[Unit]
Description=Run an application on the i.MX6

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

[Install]
WantedBy=multi-user.target

If an application depends on networking, the systemd script will want to have After=network.target in the Unit section. Once this file is in place, it can be added to automatic startup with the following:

# Enable the application to be started on boot up
systemctl enable yourapp.service

# Start the application now, but will not affect automatic startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

To set up a graphical application startup, modify the /usr/bin/mini-x-session file

At the end of the script replace matchbox-terminal with the desired application (absolute path may need to be specified):

matchbox-terminal &
exec matchbox-window-manager

The exec statement must be last in the script in order to take over this script's PID for correct operation.

Custom Build Yocto

If our stock Yocto distribution does not meet all of your needs, it is possible to re-build it with a custom set of features. Including less options for a smaller footprint, or more packages to add more features.

While we may provide guidance, our free support does not include every situation that can cause a build failure in generating custom images.

Build Yocto Distribution

Debian

Debian is a community run Linux distribution. Debian provides tens of thousands of precompiled applications and services. This distribution is known for stability and large community providing support and documentation.

Debian 12 - Bookworm

Debian 12 - Getting Started

This Debian release is available in 3 flavors with various packages.

Image	Estimated Size	Description
debian-armhf-bookworm-x11-latest.tar.bz2	925 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Debian with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools Includes X11 that launches matchbox and xterm on startup Includes touchscreen support
debian-armhf-bookworm-headless-latest.tar.bz2	681 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Debian with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools
debian-armhf-bookworm-minimal-latest.tar.bz2	223 MiB	Includes 5.10 kernel with tsimx6_minimal_defconfig that includes bare minimum driver support and kernel options required by Debian. Includes base Debian rootfs adding only what is required for Ethernet support.

The default login is root with no password.

To write this to an SD card, first partition the SD card to have one large ext3, or ext4 partition. See the guide here for more information. Once it is formatted, extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf debian-armhf-bookworm-x11-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

To rewrite the eMMC, boot to the SD card. You cannot rewrite the emmc while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedts.com/ts-arm-sbc/ts-7970-linux/distributions/debian/debian-armhf-bookworm-x11-latest.tar.bz2 | tar --numeric-owner -xj -C /mnt/emmc/
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Debian 12 - Networking

The network in Debian is configured with /etc/network/interfaces. For complete documentation, see Debian's documentation here

Some common examples are shown below. On this release network interfaces follow the predictible network interface names. Run ip addr show to get a list of the network interfaces.

Most commonly:

end0 - Ethernet device 0 (CPU Ethernet)
enp1s0 - Ethernet PCIe port 1 slot 0 ethernet
usb<mac> - USB ethernet
wlan0 - WIFI

DHCP on end0. Edit the file /etc/network/interfaces and add:

auto end0
allow-hotplug end0
iface end0 inet dhcp

Static IP on end0. Edit the file /etc/network/interfaces and add:

auto end0
iface end0 inet static
    address 192.0.2.7/24
    gateway 192.0.2.254

These will take effect on the next boot, or by restarting the networking service:

service networking restart

Debian 12 - WIFI Client

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

Install wpa_supplicant:

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

Run:

wpa_passphrase youressid yourpassword

This command will output information similar to:

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

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

/etc/network/interfaces.d/wlan0

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

To have this take effect immediately:

service networking restart

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

Debian 12 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Debian 12 - Installing New Software

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

apt-get update

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

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

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

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

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

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

Debian 12 - Setting up SSH

Openssh is installed in our default Debian image, but by default openssh does not permit root logins, and requires a password to be set. Additionally, a host key is required if one hasn't already been created on the target board. To allow remote root login:

sed --in-place 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
systemctl restart ssh.service
passwd root # Set any password

If you ssh to this system it will now support ssh as root.

Debian 12 - Starting Automatically

Bookwoorm Startup Scripts

Debian 12 - Cross Compiling

Debian provides cross toolchains within their distribution for different architectures.

For best portability we recommend using a container like docker to run a Debian 12 rootfs for the toolchain. This will allow a consistent toolchain to run from almost any Linux system that can run Docker. Keep in mind that while docker does run under OSX and Windows, these are run under a case insensitive filesystem which will cause problems with complex builds like the Linux kernel so a Linux host is still recommended.

Ubuntu/Debian:

sudo apt-get install docker.io -y

Fedora

sudo dnf install docker -y

After installing docker on any distribution make sure your user is in the docker group:

# Add your user to the docker group.  You may need to logout/log back in.
sudo usermod -aG docker $USER

Make sure you can run docker's hello world image as your user to verify it is working:

docker run hello-world

Now create a file Dockerfile:

sudo mkdir -p /opt/docker-toolchain/docker-debian-bookworm-armhf
# Use any preferred editor, vim/emacs/nano/etc
sudo nano /opt/docker-toolchain/docker-debian-bookworm-armhf/Dockerfile

# syntax = docker/dockerfile:1.2

FROM debian:bookworm

RUN dpkg --add-architecture armhf

RUN apt-get update && apt-get install -y \
    autogen \
    automake \
    bash \
    bc \
    bison \
    build-essential \
    bzip2 \
    ca-certificates \
    ccache \
    chrpath \
    cpio \
    curl \
    diffstat \
    fakeroot \
    file \
    flex \
    gawk \
    gcc-arm-linux-gnueabihf \
    git \
    gzip \
    kmod \
    libgpiod-dev:armhf \
    libncursesw5-dev \
    libssl-dev \
    libtool \
    libyaml-dev \
    locales \
    lz4 \
    lzop \
    make \
    multistrap \
    ncurses-dev \
    pkg-config \
    python3 \
    python3-cbor \
    python3-pexpect \
    python3-pip \
    qemu-user-static \
    rsync \
    runit \
    socat \
    srecord \
    swig \ 
    texinfo \
    u-boot-tools \
    zstd \
    unzip \
    vim \
    wget \
    xz-utils

# Provide a more friendly name
ENV debian_chroot debian_bookworm
RUN echo "PS1='\${debian_chroot}\\[\033[01;32m\\]@\\H\[\\033[00m\\]:\\[\\033[01;34m\\]\\w\\[\\033[00m\\]\\$ '" >> /etc/bash.bashrc

# Set up locales
RUN sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \
        echo 'LANG="en_US.UTF-8"'>/etc/default/locale && \
        dpkg-reconfigure --frontend=noninteractive locales && \
        update-locale LANG=en_US.UTF-8
ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

Next make a shell script to enter into this docker container. Create /usr/local/bin/docker-debian-bookworm:

# Use any preferred editor, vim/emacs/nano/etc
sudo nano /usr/local/bin/docker-debian-bookworm

#!/bin/bash -e

# Enters a docker running Debian 12 Bookworm
# Any arguments are run in the docker, or if no arguments it runs a shell

export TAG=debian-bookworm-armdev
SCRIPTPATH=$(readlink -f "$0")
DOCKERPATH=/opt/docker-toolchain/docker-debian-bookworm-armhf/

DOCKER_BUILDKIT=1 docker build --tag "$TAG" "$DOCKERPATH" --quiet

exec docker run --rm \
	-it \
	--volume "$(pwd)":/work \
	--user $(id -g):$(id -u) \
	-w /work \
	-e HOME=/tmp \
	"$TAG" \
	$@;

Make this executable, and call it:

sudo chmod a+x /usr/local/bin/docker-debian-bookworm

# dont run as root
docker-debian-bookworm

The first time this runs it will download a base Debian image, and run the above apt-get commands which may take around 10 or so minutes depending on your internet connection and disk speed. After it has run once, it will stay cached and adds almost no overhead to run.

This docker can be thought of as a very low overhead virtual machine that only has access to the directory where it is run.

For example, to build a simple c project, create a ~/Desktop/hello-world/hello.c:

mkdir -p ~/Desktop/hello-world/

In ~/Desktop/hello-world/hello.c:

#include <stdio.h>

int main() {
    printf("Hello world!\n");
    return 0;
}

We can now use the docker in that directory to use Debian's cross compiler to create a binary that targets armhf:

user@hostname:~$ cd ~/Desktop/hello-world/
user@hostname:~/Desktop/hello-world$ docker-debian-bookworm
sha256:a92e70c3d7346654b34c0442da20ae634901fd25d1a89dd26517e7d1c1d00c47
debian_bookworm@a8ddfa54989f:/work$ ls
hello.c
debian_bookworm@a8ddfa54989f:/work$ arm-linux-gnueabihf-gcc hello.c -o hello
debian_bookworm@a8ddfa54989f:/work$ arm-linux-gnueabihf-strip hello
debian_bookworm@a8ddfa54989f:/work$ file hello
hello: ELF 32-bit LSB pie executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=ffda981721a1531418ed1da27238707851ae0126, for GNU/Linux 3.2.0, stripped

Debian 11 - Bullseye

Debian 11 - Getting Started

The Debian images apply to the TS-4900, TS-7970, and TS-TPC-7990.

Image	Size	Kernel config	Description
debian-armhf-bullseye-latest.tar.bz2	1346 MB	ts4900_defconfig	Contains gcc, vim, X11, slim, and will autologin to an xfce4 desktop.

Once installed the default user on either image is "root" with no password.

To prepare an SD card, use partitioning tools such as 'fdisk' 'cfdisk' or 'gparted' in linux to create a single linux partition on the SD card. Once the partition is created and formatted, extract the above tarball with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf debian-armhf-bullseye-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

To rewrite the eMMC the unit must be booted to SD or any other media that is not eMMC. Once booted, run the following commands.:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-bullseye-latest.tar.bz2 | tar xj -C /mnt/emmc/
umount /mnt/emmc
sync

The same commands can be used to write a SATA drive by substituting /dev/mmcblk2p1 with /dev/sda1.

Debian 11 - Networking

The network in Debian is configured /etc/network/interfaces.d/. For complete documentation, see Debian's documentation here

Some common examples are shown below.

DHCP on eth0. Create the file: /etc/network/interfaces.d/eth0

auto eth0
allow-hotplug eth0
iface eth0 inet dhcp

Static IP on eth0. Create the file /etc/network/interfaces.d/eth0

auto eth0
iface eth0 inet static
    address 192.0.2.7/24
    gateway 192.0.2.254

These will take effect on the next boot, or by restarting the networking service:

service networking restart

Debian 11 - WIFI Client

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

Install wpa_supplicant:

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

Run:

wpa_passphrase youressid yourpassword

This command will output information similar to:

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

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

/etc/network/interfaces.d/wlan0

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

To have this take effect immediately:

service networking restart

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

Debian 11 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Debian 11 - Installing New Software

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

apt-get update

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

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

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

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

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

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

Debian 11 - Setting up SSH

Openssh is installed in our default Debian image, but by default openssh does not permit root logins, and requires a password to be set. Additionally, a host key is required if one hasn't already been created on the target board. To allow remote root login:

sed --in-place 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
systemctl restart ssh.service
/bin/ls /etc/ssh/ssh_host*key >/dev/null 2>&1  || ssh-keygen -A
passwd root # Set any password

If you ssh to this system it will now support ssh as root.

Debian 11 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

Debian 11 - Cross Compiling

Debian only provides their cross compiler for their distribution. Our examples will set up a Docker for Debian to use for development. If using Debian 11 Bullseye directly, or through a VM then the docker usage can be skipped.

Create a file called "Dockerfile" with these contents:

FROM debian:bullseye

RUN dpkg --add-architecture armhf

RUN apt-get update && apt-get install -y \
    autogen \
    automake \
    bash \
    bc \
    bison \
    build-essential \
    bzip2 \
    ca-certificates \
    ccache \
    chrpath \
    cpio \
    curl \
    diffstat \
    fakeroot \
    file \
    flex \
    gawk \
    gcc-arm-linux-gnueabihf \
    git \
    gzip \
    kmod \
    libgpiod-dev:armhf \
    libncursesw5-dev \
    libssl-dev \
    libtool \
    locales \
    lzop \
    make \
    multistrap \
    ncurses-dev \
    pkg-config \
    python \
    python3 \
    python3-pip \
    python3-pexpect \
    qemu-user-static \
    rsync \
    socat \
    runit \
    texinfo \
    u-boot-tools \
    unzip \
    vim \
    wget \
    xz-utils

# To make a more readable PS1 to show we are in the Docker
ENV debian_chroot debian_bullseye
RUN echo "PS1='\${debian_chroot}\\[\033[01;32m\\]@\\H\[\\033[00m\\]:\\[\\033[01;34m\\]\\w\\[\\033[00m\\]\\$ '" >> /etc/bash.bashrc

# Set up locales.  Needed by yocto.
RUN sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \
        echo 'LANG="en_US.UTF-8"'>/etc/default/locale && \
        dpkg-reconfigure --frontend=noninteractive locales && \
        update-locale LANG=en_US.UTF-8

ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

In the same directory as the file named "Dockerfile" run:

docker build --tag armhf-bullseye-toolchain .

When this has finished the docker can be used with:

docker run --rm -it --volume $(pwd):/work armhf-bullseye-toolchain bash

This will map the current directory to /work.

At this point the Debian Docker is ready to compile armhf binaries. For example, create a hello world in your home folder at ~/hello.c

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

To compile this enter the docker with:

docker run -it --volume $(pwd):/work armhf-bullseye-toolchain bash
# Then from the docker:
cd /work/
arm-linux-gnueabihf-gcc hello.c -o hello

Check "file hello" to verify the binary type:

debian_bullseye@b720b8ba6c1e:/work# file hello
hello: ELF 32-bit LSB pie executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=fc6389ca8da310bb5d0b87e5998b59894c078d9f, for GNU/Linux 3.2.0, not stripped

This can also be used to develop against dynamic libraries from Debian. The armhf packages can be installed in the Docker. For example, to link against curl:

# Enter the Docker:
docker run -it --volume $(pwd):/work armhf-bullseye-toolchain bash
cd /work/

apt-get install libcurl4-openssl-dev:armhf
# Download curl's simple.c example
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
arm-linux-gnueabihf-gcc simple.c -o simple -lcurl

The "simple" binary is now built for armhf and links dynamically to curl.

This will only retain the armhf libcurl package until the docker is exited. To make the changes permanent, add the package to the Dockerfile and rerun:

docker build --tag armhf-bullseye-toolchain .

Debian 10 - Buster

Debian 10 - Getting Started

The Debian images apply to the TS-4900, TS-7970, and TS-TPC-7990.

Image	Size	Kernel config	Description
debian-armhf-buster-latest.tar.bz2	1113 MB	ts4900_defconfig	Contains gcc, vim, X11, slim, and will autologin to an xfce4 desktop.

Once installed the default user on either image is "root" with no password.

To prepare an SD card, use partitioning tools such as 'fdisk' 'cfdisk' or 'gparted' in linux to create a single linux partition on the SD card. Once the partition is created and formatted, extract the above tarball with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf debian-armhf-buster-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

To rewrite the eMMC the unit must be booted to SD or any other media that is not eMMC. Once booted, run the following commands.:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- ftp://ftp.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-buster-latest.tar.bz2 | tar xj -C /mnt/emmc/
umount /mnt/emmc
sync

The same commands can be used to write a SATA drive by substituting /dev/mmcblk2p1 with /dev/sda1.

Debian 10 - Networking

The network in Debian is configured /etc/network/interfaces.d/. For complete documentation, see Debian's documentation here

Some common examples are shown below.

DHCP on eth0. Create the file: /etc/network/interfaces.d/eth0

auto eth0
allow-hotplug eth0
iface eth0 inet dhcp

Static IP on eth0. Create the file /etc/network/interfaces.d/eth0

auto eth0
iface eth0 inet static
    address 192.0.2.7/24
    gateway 192.0.2.254

These will take effect on the next boot, or by restarting the networking service:

service networking restart

Debian 10 - WIFI Client

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

Install wpa_supplicant:

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

Run:

wpa_passphrase youressid yourpassword

This command will output information similar to:

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

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

/etc/network/interfaces.d/wlan0

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

To have this take effect immediately:

service networking restart

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

Debian 10 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Debian 10 - Installing New Software

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

apt-get update

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

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

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

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

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

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

Debian 10 - Setting up SSH

Openssh is installed in our default Debian image, but by default openssh does not permit root logins, and requires a password to be set. Additionally, a host key is required if one hasn't already been created on the target board. To allow remote root login:

sed --in-place 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
systemctl restart ssh.service
/bin/ls /etc/ssh/ssh_host*key >/dev/null 2>&1  || ssh-keygen -A
passwd root # Set any password

If you ssh to this system it will now support ssh as root.

Debian 10 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

Debian 10 - Cross Compiling

Debian only provides their cross compiler for their distribution. Our examples will set up a Docker for Debian to use for development. If using Debian 10 Buster directly, or through a VM then the docker usage can be skipped.

Create a file called "Dockerfile" with these contents:

FROM debian:buster

RUN dpkg --add-architecture armhf

RUN apt-get update && apt-get install -y \
    autogen \
    automake \
    bash \
    bc \
    bison \
    build-essential \
    bzip2 \
    ca-certificates \
    ccache \
    chrpath \
    cpio \
    curl \
    diffstat \
    fakeroot \
    file \
    flex \
    gawk \
    gcc-arm-linux-gnueabihf \
    git \
    gzip \
    kmod \
    libgpiod-dev:armhf \
    libncursesw5-dev \
    libssl-dev \
    libtool \
    locales \
    lzop \
    make \
    multistrap \
    ncurses-dev \
    pkg-config \
    python \
    python3 \
    python3-pip \
    python3-pexpect \
    qemu-user-static \
    rsync \
    socat \
    runit \
    texinfo \
    u-boot-tools \
    unzip \
    vim \
    wget \
    xz-utils

# To make a more readable PS1 to show we are in the Docker
ENV debian_chroot debian_buster
RUN echo "PS1='\${debian_chroot}\\[\033[01;32m\\]@\\H\[\\033[00m\\]:\\[\\033[01;34m\\]\\w\\[\\033[00m\\]\\$ '" >> /etc/bash.bashrc

# Set up locales.  Needed by yocto.
RUN sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen && \
        echo 'LANG="en_US.UTF-8"'>/etc/default/locale && \
        dpkg-reconfigure --frontend=noninteractive locales && \
        update-locale LANG=en_US.UTF-8

ENV LC_ALL en_US.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8

In the same directory as the file named "Dockerfile" run:

docker build --tag armhf-buster-toolchain .

When this has finished the docker can be used with:

docker run --rm -it --volume $(pwd):/work armhf-buster-toolchain bash

This will map the current directory to /work.

At this point the Debian Docker is ready to compile armhf binaries. For example, create a hello world in your home folder at ~/hello.c

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

To compile this enter the docker with:

docker run -it --volume $(pwd):/work armhf-buster-toolchain bash
# Then from the docker:
cd /work/
arm-linux-gnueabihf-gcc hello.c -o hello

Check "file hello" to verify the binary type:

user@host:~/$ file hello
hello: ELF 32-bit LSB pie executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0, BuildID[sha1]=8a8cee3341d3ef76ef6796f72d5722ae9d77c8ea, not stripped

This can also be used to develop against dynamic libraries from Debian. The armhf packages can be installed in the Docker. For example, to link against curl:

# Enter the Docker:
docker run -it --volume $(pwd):/work armhf-buster-toolchain bash
cd /work/

apt-get install libcurl4-openssl-dev:armhf
# Download curl's simple.c example
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
arm-linux-gnueabihf-gcc simple.c -o simple -lcurl

The "simple" binary is now built for armhf and links dynamically to curl.

This will only retain the armhf libcurl package until the docker is exited. To make the changes permanent, add the package to the Dockerfile and rerun:

docker build --tag armhf-buster-toolchain .

Debian 9 - Stretch

Debian 9 - Getting Started

We provide two images for Debian Stretch which apply to our TS-4900, TS-7970, and TS-TPC-7990. If you are unsure which image to pick, use the larger image which contains more development tools and drivers.

Image	Size	Kernel config	Description
debian-armhf-stretch-latest.tar.bz2	1279MB	ts4900_defconfig	Contains gcc, vim, X11, slim, and will autologin to an xfce4 desktop.
debian-armhf-stretch-minimal-latest.tar.bz2	184MB	ts4900_tiny_defconfig	Stripped down Debian containing bare minimal hardware support, very limited peripheral support, and only the core debian packages.

Once installed the default user on either image is "root" with no password.

To prepare an SD card, use partitioning tools such as 'fdisk' 'cfdisk' or 'gparted' in linux to create a single linux partition on the SD card. Once the partition is created and formatted, extract the above tarball with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf debian-armhf-stretch-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

To rewrite the eMMC the unit must be booted to SD or any other media that is not eMMC. Once booted, run the following commands.:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- ftp://ftp.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-stretch-latest.tar.bz2 | tar xj -C /mnt/emmc/
umount /mnt/emmc
sync

The same commands can be used to write a SATA drive by substituting /dev/mmcblk2p1 with /dev/sda1.

Debian 9 - Networking

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

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

To set up a static IP:

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

To make this take effect immediately for either option:

service networking restart

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

Debian 9 - WIFI Client

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

Install wpa_supplicant:

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

Run:

wpa_passphrase youressid yourpassword

This command will output information similar to:

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

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

/etc/network/interfaces.d/wlan0

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

To have this take effect immediately:

service networking restart

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

Debian 9 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Debian 9 - Application Development

Debian 9 - Stretch Cross Compiling

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

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

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

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

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

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

To compile this:

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

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

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

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

apt-get install libcurl4-openssl-dev:armhf

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

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

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

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

Debian 9 - Installing New Software

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

apt-get update

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

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

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

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

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

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

Debian 9 - Setting up SSH

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

apt-get install openssh-server

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

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

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

Debian 9 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

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

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

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

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

exec xfce4-terminal

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

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

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

Debian 8 - Jessie

Debian 8 - Getting Started

Once installed, the default user is "root" with no password.

debian-armhf-jessie-latest.tar.bz2 (md5)

Note:

This is a shared image that supports the TS-4900, TS-7970, and TS-TPC-7990.

To prepare an SD card, use partitioning tools such as 'fdisk' 'cfdisk' or 'gparted' in linux to create a single linux partition on the SD card. Once the partition is set up and formatted, extract the above tarball with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf debian-armhf-jessie-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

To rewrite the eMMC the unit must be booted to SD or any other media that is not eMMC. Once booted, run the following commands.:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-jessie-latest.tar.bz2 | tar xj -C /mnt/emmc/
umount /mnt/emmc
sync

The same commands can be used to write a SATA drive by substituting /dev/mmcblk2p1 with /dev/sda1.

Debian 8 - Networking

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

# Bring up the CPU network interface
ifconfig eth0 up

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

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

# Set a specific subnet
ifconfig eth0 192.168.0.50 netmask 255.255.0.0

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

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

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

Configure DHCP in Debian:

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

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

/etc/systemd/network/eth.network

[Match]
Name=eth*

[Network]
DHCP=yes

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

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

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

/etc/systemd/network/eth0.network

[Match]
Name=eth0

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

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

Debian 8 - WIFI Client

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

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

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

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

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

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

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

[Match]
Name=wlan0

[Network]
DHCP=yes

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

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

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

Debian 8 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Debian 8 - Application Development

Debian 8 - Jessie Cross Compiling

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

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

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

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

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

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

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

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

To compile this:

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

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

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

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

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

apt-get install libcurl4-openssl-dev:armhf

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

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

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

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

Debian 8 - Installing New Software

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

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

Jessie:

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

Wheezy:

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

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

apt-get update

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

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

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

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

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

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

Debian 8 - Setting up SSH

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

apt-get install openssh-server

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

passwd root

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

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

Note:

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

Debian 8 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

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

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

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

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

exec xfce4-terminal

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

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

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

Ubuntu

Ubuntu is a distribution provided by Canonical which is based on Debian. Ubuntu often has more recent packages but follows a shorter release cycle. The image we provide is based on Ubuntu. We use the root filesystem, but the kernel is not provided by Ubuntu or in any way associated with Canonical.

This image includes support for the TS-4900, TS-7970, and TS-TPC-7990.

Ubuntu 24.04 - Noble

Ubuntu 24.04 - Getting Started

This Ubuntu release is available in 3 flavors with various packages.

Image	Estimated Size	Description
ubuntu-armhf-24.04-x11-latest.tar.bz2	1091 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Ubuntu with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools Includes X11 that launches matchbox and xterm on startup Includes touchscreen support
ubuntu-armhf-24.04-headless-latest.tar.bz2	866 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Ubuntu with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools
ubuntu-armhf-24.04-minimal-latest.tar.bz2	190 MiB	Includes 5.10 kernel with tsimx6_minimal_defconfig that includes bare minimum driver support and kernel options required by Ubuntu. Includes base Ubuntu rootfs adding only what is required for Ethernet support.

The default login is "user/user" which includes sudo permissions.

To write this to an SD card, first partition the SD card to have one large ext3, or ext4 partition. See the guide here for more information. Once it is formatted, extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf ubuntu-armhf-24.04-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

To rewrite the eMMC, boot to the SD card. You cannot rewrite the emmc while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/ubuntu/ubuntu-armhf-24.04-x11-latest.tar.bz2 | tar --numeric-owner -xj -C /mnt/emmc/
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Ubuntu 24.04 - Networking

The network in Ubuntu is configured netplan. For complete documentation, see Netplan's documentation here

Some common examples are shown below. On this release network interfaces follow the predictible network interface names. Run ip addr show to get a list of the network interfaces.

Most commonly:

end0 - Ethernet device 0 (CPU Ethernet)
enp1s0 - Ethernet PCIe port 1 slot 0 ethernet
usb<mac> - USB ethernet
wlan0 - WIFI

DHCP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
      dhcp4: true
      dhcp6: true

Static IP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
     dhcp4: no
     addresses: [192.168.0.50/24]
     gateway4: 192.168.0.1
     nameservers:
       addresses: [8.8.8.8,8.8.4.4]

After creating the yaml file, set the appropriate permissions and apply the netplan:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

Ubuntu 24.04 - WIFI Client

Wireless configuration under Ubuntu, similar to Ethernet, also uses netplan for configuration. For example, create /etc/netplan/wifi.yaml:

network:
  version: 2
  renderer: networkd
  wifis:
    wlan0:
      dhcp4: yes
      dhcp6: yes
      access-points:
        "yourssid":
          password: yourpassphrase"

After creating the yaml file, set the appropriate permissions and apply the netplan:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

Ubuntu 24.04 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Ubuntu 24.04 - Installing New Software

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

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.

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

In this case you will likely want openjdk-7-jre to provide a runtime environment, and possibly openjdk-7-jdk to provide a development environment.

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-7-jre
# You can also chain packages to be installed
apt-get install openjdk-7-jre nano vim mplayer

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

Ubuntu 24.04 - Setting up SSH

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

apt-get install openssh-server

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

passwd root

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

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

Note:

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

Ubuntu 24.04 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

Ubuntu 23.04 - Lunar

Ubuntu 23.04 - Getting Started

This Ubuntu release is available in 3 flavors with various packages.

Image	Estimated Size	Description
ubuntu-armhf-23.04-x11-latest.tar.bz2	1068 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Ubuntu with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools Includes X11 that launches matchbox and xterm on startup Includes touchscreen support
ubuntu-armhf-23.04-headless-latest.tar.bz2	845 MiB	Includes 5.10 kernel with tsimx6_defconfig that includes broad driver support Base Ubuntu with common utils Common embedded tools (i2c, can, gpio, iio, serial tools, etc) Includes hardware support Networking tools (ethernet, wifi, bluetooth) Includes Development tools
ubuntu-armhf-23.04-minimal-latest.tar.bz2	207 MiB	Includes 5.10 kernel with tsimx6_minimal_defconfig that includes bare minimum driver support and kernel options required by Ubuntu. Includes base Ubuntu rootfs adding only what is required for Ethernet support.

The default login is "user/user" which includes sudo permissions.

To write this to an SD card, first partition the SD card to have one large ext3, or ext4 partition. See the guide here for more information. Once it is formatted, extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf ubuntu-armhf-23.04-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

To rewrite the eMMC, boot to the SD card. You cannot rewrite the emmc while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/ubuntu/ubuntu-armhf-23.04-x11-latest.tar.bz2 | tar --numeric-owner -xj -C /mnt/emmc/
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Ubuntu 23.04 - Networking

The network in Ubuntu is configured netplan. For complete documentation, see Netplan's documentation here

Some common examples are shown below. On this release network interfaces follow the predictible network interface names. Run ip addr show to get a list of the network interfaces.

Most commonly:

end0 - Ethernet device 0 (CPU Ethernet)
enp1s0 - Ethernet PCIe port 1 slot 0 ethernet
usb<mac> - USB ethernet
wlan0 - WIFI

DHCP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
      dhcp4: true
      dhcp6: true

Static IP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
     dhcp4: no
     addresses: [192.168.0.50/24]
     gateway4: 192.168.0.1
     nameservers:
       addresses: [8.8.8.8,8.8.4.4]

After creating the yaml file, set the appropriate permissions and apply the netplan:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

Ubuntu 23.04 - WIFI Client

Wireless configuration under Ubuntu, similar to Ethernet, also uses netplan for configuration. For example, create /etc/netplan/wifi.yaml:

network:
  version: 2
  renderer: networkd
  wifis:
    wlan0:
      dhcp4: yes
      dhcp6: yes
      access-points:
        "yourssid":
          password: yourpassphrase"

After creating the yaml file, set the appropriate permissions and apply the netplan:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

Ubuntu 23.04 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Ubuntu 23.04 - Installing New Software

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

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.

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

In this case you will likely want openjdk-7-jre to provide a runtime environment, and possibly openjdk-7-jdk to provide a development environment.

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-7-jre
# You can also chain packages to be installed
apt-get install openjdk-7-jre nano vim mplayer

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

Ubuntu 23.04 - Setting up SSH

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

apt-get install openssh-server

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

passwd root

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

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

Note:

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

Ubuntu 23.04 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

Ubuntu 20.04 - Focal

Ubuntu 20.04 - Getting Started

The latest release is available here:

ubuntu-armhf-20.04-latest.tar.bz2

The login is either "root" with no password, or username "ubuntu" with the password "ubuntu". The ubuntu user is allowed to run sudo.

To write this to an SD card, first partition the SD card to have one large ext3, or ext4 partition. See the guide here for more information. Once it is formatted, extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf ubuntu-armhf-20.04-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

To rewrite the eMMC, boot to the SD card. You cannot rewrite the emmc while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/ubuntu/ubuntu-armhf-20.04-latest.tar.bz2 | tar --numeric-owner -xj -C /mnt/emmc/
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Ubuntu 20.04 - Networking

The network in Ubuntu is configured netplan. For complete documentation, see Netplan's documentation here

Some common examples are shown below. On this release network interfaces follow the predictible network interface names. Run ip addr show to get a list of the network interfaces.

Most commonly:

end0 - Ethernet device 0 (CPU Ethernet)
enp1s0 - Ethernet PCIe port 1 slot 0 ethernet
usb<mac> - USB ethernet
wlan0 - WIFI

DHCP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
      dhcp4: true
      dhcp6: true

Static IP on end0. Edit the file /etc/netplan/ethernet.yaml and add:

network:
  version: 2
  renderer: networkd
  ethernets:
    end0:
     dhcp4: no
     addresses: [192.168.0.50/24]
     gateway4: 192.168.0.1
     nameservers:
       addresses: [8.8.8.8,8.8.4.4]

After creating the yaml file, set the appropriate permissions and apply the netplan:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

Ubuntu 20.04 - WIFI Client

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

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

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

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

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

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

Next, enable the service to start up on boot:

systemctl enable wpa_supplicant@wlan0

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

[Match]
Name=wlan0

[Network]
DHCP=yes

Enable networkd to run dhcp on startup:

systemctl enable systemd-networkd

See the systemctl-networkd example for setting a static IP for a network interface. The wlan0.network can be configured the same way as an eth.network. To enable all of the changes that have been made, run the following commands:

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

Ubuntu 20.04 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Ubuntu 20.04 - Installing New Software

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

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.

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

In this case you will likely want openjdk-7-jre to provide a runtime environment, and possibly openjdk-7-jdk to provide a development environment.

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-7-jre
# You can also chain packages to be installed
apt-get install openjdk-7-jre nano vim mplayer

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

Ubuntu 20.04 - Setting up SSH

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

apt-get install openssh-server

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

passwd root

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

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

Note:

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

Ubuntu 20.04 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

Ubuntu 18.04 - Xenial

Ubuntu 18.04 - Getting Started

The latest release is available here:

ubuntu-armhf-18.04-latest.tar.bz2

The login is either "root" with no password, or username "ubuntu" with the password "ubuntu". The ubuntu user is allowed to run sudo.

To write this to an SD card, first partition the SD card to have one large ext3, or ext4 partition. See the guide here for more information. Once it is formatted, extract this tar with:

# Assuming your SD card is /dev/sdc with one partition
mkfs.ext3 /dev/sdc1
mkdir /mnt/sd/
sudo mount /dev/sdc1 /mnt/sd/
sudo tar --numeric-owner -xjf ubuntu-armhf-18.04-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

To rewrite the eMMC, boot to the SD card. You cannot rewrite the emmc while it is mounted elsewhere, or used to currently boot the system. Once booted to the SD, run:

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget -qO- https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/ubuntu/ubuntu-armhf-18.04-latest.tar.bz2 | tar --numeric-owner -xj -C /mnt/emmc/
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Ubuntu 18.04 - Networking

From almost any Linux system you can use "ip" or the ifconfig/route commands to set up the network.

# Bring up the CPU network interface
ifconfig eth0 up

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

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

# Set a specific subnet
ifconfig eth0 192.168.0.50 netmask 255.255.0.0

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

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

Most networks will offer DHCP which can be set up with one command:

# 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

To make DHCP run on startup systemd's networking will need to be configured.

In /etc/systemd/network/eth.network

[Match]
Name=eth*

[Network]
DHCP=yes

Then, if you intend to use DHCP to configure your DNS, start and enable the network name resolver service:

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

For a static configuration create a config file for that specific interface. /etc/systemd/network/eth0.network

[Match]
Name=eth0

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

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

Ubuntu 18.04 - WIFI Client

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

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

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

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

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

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

Next, enable the service to start up on boot:

systemctl enable wpa_supplicant@wlan0

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

[Match]
Name=wlan0

[Network]
DHCP=yes

Enable networkd to run dhcp on startup:

systemctl enable systemd-networkd

See the systemctl-networkd example for setting a static IP for a network interface. The wlan0.network can be configured the same way as an eth.network. To enable all of the changes that have been made, run the following commands:

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

Ubuntu 18.04 - WIFI Access Point

First, hostapd needs to be installed in order to manage the access point on the device:

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

Note:

The install process will start an unconfigured hostapd process. This process must be killed and restarted before a new hostapd.conf will take effect.

Edit /etc/hostapd/hostapd.conf to include the following lines:

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 start up an access point that can be detected by WIFI clients. A DHCP server will likely be desired to assign IP addresses. Refer to Debian's documentation for more details on DHCP configuration.

Ubuntu 18.04 - Installing New Software

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

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.

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

In this case you will likely want openjdk-7-jre to provide a runtime environment, and possibly openjdk-7-jdk to provide a development environment.

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-7-jre
# You can also chain packages to be installed
apt-get install openjdk-7-jre nano vim mplayer

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

Ubuntu 18.04 - Setting up SSH

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

apt-get install openssh-server

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

passwd root

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

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

Note:

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

Ubuntu 18.04 - Starting Automatically

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

[Unit]
Description=Run an application on startup

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

[Install]
WantedBy=multi-user.target

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

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

# Start the app now, but doesn't change auto startup
systemctl start yourapp.service

Note:

See the systemd documentation for in depth documentation on services.

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

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

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

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

exec xfce4-terminal

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

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

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

Ubuntu Core

Ubuntu Core is a new distribution provided by Canonical targetted towards embedded/IoT projects. This requires users to generate "snap" packages for their application, but provides a mechanism for save remote updates to the OS and packages. Our kernel is based on Ubuntu 16's 4.4 based kernel to provide the best compatibility and support. Bug fixes to units using our kernel snap are provided through the ubuntu core app store.

Getting Started with Ubuntu Core

Download our latest image here. The image unpacks to 1 GB, an SD card of equal or larger size must be used.

Write this to an SD card with:

wget ftp://ftp.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions\
/ubuntu-core/ubuntu-core-16-latest.img.bz2
bzip2 -d ubuntu-core-16-latest.img.bz2
# Assuming /dev/sdd is your SD card.  Check dmesg after inserting for your device.
# Make sure this is the block device (/dev/sdd) and not a partition (/dev/sdd1).
dd if=/path/to/ubuntu-core-16-latest.img bs=4M of=/dev/sdd conv=fsync && sync

This can be written to emmc using the Image Replicator.

Next make an Ubuntu SSO account. Generate SSH keys and upload your SSH keys to your account.

Once written to either boot media start up the TS-4900. Upon first boot there is a configuration tool that must be run to link up with the Ubuntu SSO system. The first boot requires a connection to the serial console in order to work through the configuration steps. It is highly recommended to make an account and upload SSH keys as outlined above before booting up the system the first time. Additionally, we recommend you connect the TS-4900 to a local wired network before running the configuration utility. It is possible to set up a WiFi connection during the configuration stage if desired rather than a wired connection.

When Ubuntu Core is booted on the TS-4900 for the first time, the following prompt will be given on the serial console:

Press Enter to Configure

Ubuntu core has no default username/password, the configuration tool will import the SSH keys to allow login.

Press enter and it will have you confirm DHCP, or use a static network configuration. Once configured it will ask for your Ubuntu SSO username. This will create an account on the Ubuntu Core image and allow access only with your SSH keys present on the store. After it has fetched the keys it will print out the command to connect to your unit which will allow password-less access only from the approved hosts.

Connect to the board with:

ssh <ubuntu SSO username>@<IP of board>

Note:

This must be run a host that has been approved through the Ubuntu SSO system. That is, SSH keys created on it and uploaded through the Ubuntu SSO system.

Once connected, a normal linux shell prompt is given. From here, the system can be interacted with. See http://snapcraft.io/ for more information on developing and installing snaps for your application. Custom snaps can be created and uploaded through the Ubuntu snap store. Custom snaps can be made private or public. The Ubuntu SSO system links the previously created account to the http://snapcraft.io/ website, linking everything together.

Note:

The first boot of the Ubuntu Core image will modify U-Boot environment. Reverting back to an image that has never been booted will cause U-Boot to error. This can be fixed in U-Boot by running the command "run clearenv" and then rebooting the unit.

Ubuntu Core Reference Links

QNX

QNX is an RTOS that supports the i.MX6 CPU. We provide a BSP for the TS-4900 and TS-7970 quad core or solo based on QNX Neutrino 6.6.0. The supporting files are available here:

Disk Image: ts7970-qnx-6.6.0-latest.dd.bz2 (md5)
Quad core source BSP_freescale-imx6q-ts7970-latest.tar.gz (md5)
Solo core source BSP_freescale-imx6dl-ts7970-latest.tar.gz (md5)

We provide support for booting QNX on our platforms, but further support is provided by QNX

QNX Support

Known Working:

UARTs 1-5
Ethernet
I2C 1, I2C 2
SD (/dev/hd0)
eMMC (/dev/emmc0)
USB Host
SPI NOR (/dev/fs0)
HDMI (TS-7970 only)
LCD Interface (TS-TPC-8390 with TS-4900 only)
RS485

Known not working:

WIFI
FPGA based UARTs

Not yet tested:

I210 (Second gig eth)

QNX BSP

Before compiling QNX be sure to edit the file: src/hardware/startup/boards/imx6x/ts7970/board.h Set either BOARD_TS7970 or BOARD_TS4900 depending on the target board.

We have also included a port of tshwctl which is used to access the FPGA. This allows you to read/write FPGA registers and to change the crossbar. For example, to set up auto TXEN on the TS-7970 RS-485 port (/dev/ser4):

export MB_TXD=TTYSER4_TXD
export TTYMAX1_RXD=GPIO
export TTYSER4_RXD=MB_RXD_485
export TXD_232_COM=GPIO
export MB_TX_EN_485=TTYSER4_TXEN
tshwctl -b 0x7970 -s

tshwctl -b 0x7970 -c

This will print out the modified state of the crossbar. The relevant pins are now:

  TTYSER4_RXD ( in) (  0) MB_RXD_485  
       MB_TXD ( in) (  0) TTYSER4_TXD
 MB_TX_EN_485 ( in) (  0) TTYSER4_TXEN                                          
  TTYMAX1_RXD ( in) (  0) GPIO                                                  
  TXD_232_COM ( in) (  0) GPIO

Use tshwctl to specify the baud rate and mode of the uart so the TX enable pin will be automatically toggled.

tshwctl -b 0x7970 -a 4 -x 115200 -i 8n1

/dev/ser4 is now configured for RS485 traffic.

QNX Booting

Write the example image to a disk.

bzip2 -d ts7970-qnx-6.6.0-20150707.dd.bz2

#Replace sdx with your device.  Try lsblk to find your SD card.
sudo dd if=ts7970-qnx-6.6.0-20150707.dd bs=4M of=/dev/sdx
sync

Reinsert or partprobe the disk, and there will be a single partition present. The partition includes the QNX IFS, and a u-boot script. On startup the imx6 is configured to launch the hush script. If present, at /boot/boot.ub on either the SD or eMMC depending on if the SD boot jumper is present. The script loads the FPGA, then copies the QNX ifs into memory and jumps into it to begin execution.

Windows CE 2013

Installing

The example Windows image for the TS-4900 (Solo (TS-4900-S-WIN-I) or Quad-core (TS-4900-Q-WIN-E)) is available from Guruce here. The download kit includes all utilities and instructions necessary to install both Windows Embedded Compact 2013 and the associated SDK for development on the TS-4900 in Visual Studio. Care should be taken to obtain the "solo" or "quad core" version appropriate for the TS-4900 device actually being used.

FPGA

The FPGA on the TS-4900 is a soft-programmable ICE40. In Linux, loading of the default FPGA image is handled by the OS bootloader. In the case of Windows, this functionality is separate. Technologic Systems provides an example of how to load this file in the git archive at the embeddedTS github. Note, GuruCE version r1100 and previous do not set up the FPGA clock pin. In this case user intervention on the serial console is required during boot. See the [#r1100_special_instructions] for information on this workaround.

r1100

To temporarily enable the FPGA clock on the TS-4900, break into the eBoot bootloader by pressing space bar during the first second of powerup. Press B at the eBoot menu to drop to eBoot console, then enter "s 0x020E022C 0x3" at the prompt (without the quotation marks), press enter, q, r, l, and wait for the nk.bin to load. The FPGA clock is now running and your FPGA loader can function as designed.

Backup / Restore

While all of our products ship with images pre-loaded in to any supplied media, there are many situations where new images may need to be written. For example, to restore a device to its factory settings or apply a customized image/filesytem for application deployment. Additionally, specific units may be used for development and that unit's disk images need to be replicated to other units to be deployed in the field.

We offer a number of different ways to accomplish both capturing images to be written to other units, and the actual writing process itself. See the sections below for details on our USB Image Replicator tool to capture and/or write images, as well as details on manual processes to capture and write images on each of this device's media.

Image Replicator

This platform supports our Image Replicator tool. The Image Replicator tool is intended for use by developers as a means to write bootable images or filesystems on to a device's media (SD / eMMC / SATA / etc.) as part of their production or preparation process. In addition to writing media, the Image Replicator tool is capable of capturing images from a device's media and preparing them to be written to other devices.

The Image Replicator tool is a USB disk image that can be booted on a target device to capture or write its media directly without the need for a host workstation. The USB disk image is based on Buildroot and contains a set of scripts which handle the capture and write process. The process and its scripts are flexible and can be used as-is or adapted in to larger production processes to format and load data on to devices. The single USB drive can be used to capture images from a device, and then can be inserted in to other devices to write those same images on to other devices. The capture process is not necessary if it is not needed. Images for the target device can be copied to the USB drive, booted on compatible units, and have the target images written to that unit's media.

Image Capture Process

The image capture process performs the following steps. For more detailed information, see the Image Capture section below.

If no valid images exist on the disk, image capture starts.
For each valid media present on the unit, a bit for bit copy of the source is made.
This image is mounted, sanitized (to remove unneeded files and allow safe copying of the image to other units), and saved as either a disk image or a tarball depending on the partition layout of the source disk.
All images and tarballs are compressed, with both the output files having their MD5 hash saved as well as all of the files contained in the root partition having their MD5 hashes saved to a file for later verification.

The captured images and tarballs are named such that the USB Image Replicator disk can be immediately used to boot another unit and have it perform the Image Write process to write that unit's media with the captured images.

Note:

When using this process, the USB drive used for the Image Replicator must be sized large enough to handle multiple compressed images as well as the uncompressed copy of the media image actively being worked with. If the image capture process runs out of space, the process will indicate a failure.

Image Write Process

The image write process performs the following steps. For more details information see the Image Write section below.

For each valid media present on the unit, find the first valid source image file for it.
If a source image exists for a media that is not present on the unit, then the process indicates a failure.
If the source image is a tarball, format the target disk with an appropriate filesystem, and unpack it to the target disk, verifying all files against the MD5 hash file list after they are written.
If the source image is a disk image, write that to the target disk. If an MD5 file for the disk image exists, read back the written disk and compare it to the hash.

Creating a USB Image Replicator Disk

Image Replicator USB disk images can be found below:

Disk image: tsimx6-usb-image-replicator.dd.xz

Tarball: tsimx6-usb-image-replicator-rootfs.tar.xz

Two types of USB Image Replicator images are available for this platform, a tarball and an actual disk image. They both have the same contents and are intended to provide different methods to write the Image Replicator tool to a USB disk.

Disk Image (.dd.xz): The disk image is easier to write from different workstation OSs, will auto-expand to the full disk length on its first boot, and is intended to be used for image capture (and later image writing) due to its small size and auto-expansion process. We recommend this route for users who may not have access to a Linux workstation or need to capture images from a golden unit first.

Tarball Image (.tar.xz): The tarball image is easiest to write from a Linux workstation, but requires creating a partition table on the USB disk (if one does not already exist), formatting the filesystem, and unpacking the tarball. It can readily be used for for both image capture and writing, but is the easiest route when image capture is not needed due to the auto-expansion process.

Note:

It is recommended to use USB drives with solid-state media for this process. Slower USB drives, especially those with spinning media, may take too long to enumerate and the bootloader will not boot the Image Replicator disk. Additionally, the use of low quality, damaged, and/or worn out USB drives may cause unexpected errors that appear unrelated to the USB drive itself. If there are issues using the Image Replicator, we recommend first trying a new, fresh, high-quality USB drive from a trusted named brand.

Disk Image

This process uses a small disk image that can be written to a USB device. This disk image uses an ext3 filesystem which expands on its first boot to the full length of the disk before beginning the image capture process. This disk is recommended for users who may not have access to a Linux workstation or who need to capture images from a golden unit.

It is possible to use the disk image for just image writing, however, in order to ensure full disk space is available it is recommended to write the disk image to a USB drive, set the IR_NO_CAPTURE_* Image Replicator Runtime Options, boot it on the target unit, let the system boot and expand the disk, insert the USB drive back in to a workstation, and then copy in the desired image files for the target unit from the workstation.

Writing Disk Image From a Linux Workstation

The disk image can be written via the command line with the dd command (replace /dev/sdX with the correct USB device node):

xzcat <platform>-usb-image-replicator.dd.xz > /dev/sdX

Graphical tools also exist for this purpose, for example balenaEtcher^[1] offers this functionality.

Writing Disk Image From a Windows Workstation

A number of tools exist for writing an image to a USB drive, including (but not limited to) balenaEtcher^[1] and Win32DiskImager^[2]

Writing Disk Image From a MacOS Workstation

We recommend using a tool such as balenaEtcher^[1] to write disk images.

↑ ^1.0 ^1.1 ^1.2 embeddedTS is not affiliated with this tool. balenaEtcher version 1.5.101 tested in Windows 10 on 20220216
↑ embeddedTS is not affiliated with this tool. Win32DiskImager 1.0.0 tested in Windows 10 on 20220216. Cannot handle compressed images, must first decompress disk image.

Tarball

This process is easiest on a Linux workstation, but can be performed on other operating systems as well so long as they can support a compatible filesystem, the xz compression algorithm, as well as the tarball archive format. Note that in many cases, one of our computing platforms running our stock Linux image can be used if a Linux workstation is not available. After writing the tarball to a USB disk, the full length of the USB disk would be available to copy source images to in order to write them to other units.

The image replicator and scripts require a minimum of 50 MB; this plus the size of any target disk images or tarballs to be used dictates the minimum USB disk size required. The USB drive should have only a single partition, which is formatted ext2^[1] / 3 / 4^[2] or FAT32/vfat^[3] Note that other filesystems are not compatible with U-Boot and therefore cannot be used.

Writing Tarball From a Linux Workstation

# This assumes USB drive is /dev/sdc:
sudo mkfs.ext3 /dev/sdc1
sudo mkdir /mnt/usb/
sudo mount /dev/sdc1 /mnt/usb/
sudo tar --numeric-owner -xf /path/to/<platform>-usb-image-replicator-rootfs.tar.xz -C /mnt/usb/
sudo umount /mnt/usb/

Writing Tarball From a Windows Workstation

It is recommended to use a third party tool, as native Windows archive tools have been observed to not work correctly. Tools such as 7-Zip^[4] or PeaZip^[5] are known working. It may also be possible to use Windows Subsystem for Linux following the Linux Workstation instructions above, but this has not been tested.

Note that some Windows tools may attempt to use the whole disk, rather than create a partition table. A partition table with a single partition is required for U-Boot support.

With a formatted USB disk, the archive can be unpacked to the root folder of the USB disk. Be sure to not unpack the tarball contents in to a new folder on the drive as this will not be bootable.

↑ The ext2 filesystem has a max file size limit as low at 16 GiB. This may cause issues for Image Capture.
↑ Use of ext4 may require additional options. U-Boot on some platforms does not support the 64-bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options -O ^64bit,^metadata_csum may need to be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed, nor are they needed for ext2 / 3.
↑ The FAT32 (supported by vfat in Linux) filesystem has a max file size limit of 4 GiB. This may cause issues for Image Capture.
↑ embeddedTS is not affiliated with this tool. 7-Zip 21.07 tested in Windows 10 on 20220222
↑ embeddedTS is not affiliated with this tool. PeaZip 7.2.0 tested in Windows 10 on 20220222

Running the Image Replicator Tool

Once a USB drive is formatted with the Image Replicator tool (see Creating a USB Image Replicator Disk for the correct files and process), boot to this USB drive (note that the Image Replicator already sets up the correct U-Boot boot scripts to boot to the USB drive, see the aforementioned section for details on how to make U-Boot call the scripts on the USB drive). This will start either image capture if no disk images/tarballs are present on the USB drive, or image write if there are disk images/tarballs present on the USB drive.

Image Replicator Runtime Options

Some of the runtime operations of the Image Replicator can be specified. These are handled by creating empty files in the root folder of the bootable USB drive. When booted, these files are analyzed and actions taken based on them.

Option	Description
`IR_NO_CAPTURE_SD` `IR_NO_CAPTURE_SD1` `IR_NO_CAPTURE_EMMC` `IR_NO_CAPTURE_SATA`	When capturing, skip media matching this name. See the respective platform manual for information on which names correspond to which physical media. Note that the names are generic and match what the media is captured as, regardless of actual device node. The names are uniform between capture and write for a given system.
`IR_NO_COMPRESS`	When capturing, do not compress the data. On slower systems, slower disks, or systems with a large amount of data to capture, the final compression can take a significant amount of time. This option will allow a capture, but will not attempt to compress it.
`IR_SHELL_ONLY`	When booting, skip doing any of the image replication process (Capture or Write) and instead drop to a login prompt. Useful for debugging. Note that, to prevent any confusion the system will indicate a non-critical failure when skipping any of the Image Replication process.

Image Replicator LED Status

The green and red LEDs of the platform are used to indicate status.

Any LED patterns not matching the table below indicate different operational states of the platform itself, e.g. executing the bootloader, the kernel is running but Image Replicator has not yet started, etc.

Green	Red	State	Description
Short Strobe	Solid	Running	The Image Replicator process is running.
0.5 Hz Blink	Off	Succeeded	All operations being performed by the Image Replicator have completed successfully.
Off	0.5 Hz Blink	Non-critical Failure	One or more operations being performed by the Image Replicator have failed to complete. View logs in `/tmp/logs/` as well as the failure reason in `/tmp/failed`
Off	4 Hz Blink	Critical Failure	An operation has failed in a way that could leave the device inoperable if power were to be removed. View logs in `/tmp/logs` as well as the failure reason in `/tmp/failed`.

Image Capture

If no valid images to write exist on the booted USB Image Replicator drive, the image capture process starts automatically.

Note that while in progress, the USB Image Replicator drive is mounted read-write. It is not advised to remove power or disconnect the USB Image Replicator drive until the whole process has completed.

To help diagnose failures, files in /tmp/logs/ contain output from each capture process.

For each media present on the unit (SD / eMMC / SATA / etc.), the image capture process will do the following:

Copy the entire media image to an appropriately named file on the USB Image Replicator drive, e.g. sdimage.dd. No data is written to the source media and it is never mounted. The source disk can follow the stock partition layout, or implement a customized one.
Perform an fsck on the Linux rootfs partition in the image file. Note that, if deviating from the standard partition layout, it may be necessary to modify the scripts handling the capture process.
Mount the Linux rootfs partition from the image file and sanitize the filesystem. The sanitization process removes temporary files (e.g. /log/ files), unique files (e.g. ssh private key files, machine ID files), adds a file to indicate that it is a custom image with the date as its contents, etc. The full list of operations can be found in this script. It may be necessary to modify this file for unique situations.
If the media's partition layout uses only a single partition, the filesystem is packed in to a tarball on the USB Image Replicator drive which is appropriately named and compressed, e.g. sdimage.tar.xz. The image file is then unmounted and removed from the USB Image Replicator drive.
If the media's partition layout uses multiple partitions, the image file is then unmounted, an md5sum of the image file taken, it is compressed and appropriately named on the USB Image Replicator drive, e.g. emmcimage.dd.xz, and then an md5sum of the compressed image is taken.

Note that when using this process, the USB Image Replicator drive that is used must be sized large enough to handle multiple compressed images as well as the uncompressed copy of the media image actively being worked with. If the image capture process runs out of space, the process will indicate a failure via the LEDs.

The images files captured are saved to the root folder of the USB Image Replicator drive. Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image capture process, see this script.

Image Write

This process is used to write existing images to media on a target unit. If appropriately named disk images or tarballs (see table below) are present in the root folder of the USB Image Replicator drive when booted, then the startup scripts will start the image writing process. The latest disk images we provide for our platforms can be downloaded from our FTP site, see the backup and restore section for links to these files.

Note that the USB Image Replicator drive remains read-only through the entire process but target devices may be mounted or actively written. It is not advised to remove power or disconnect the USB Image Replicator drive until the whole process has completed.

To help diagnose failures, files in /tmp/logs/ contain output from each writing process.

The Image Replicator script expects disk images or tarballs to have specific names to match the target media. The script will attempt to match tarball and then disk image names (in the order they are listed in the table below) for each target media, using the first file that is found to write to the target media. Note that symlinks can be used on the USB Image Replicator disk if formatted with a filesystem that supports symlinks. This can be used, for example, to write the same tarball to both SD and eMMC from only a single copy of the source tarball.

Upon completion, it is safe to remove power or unplug the USB drive.

For more details on the image write process, see this script.

The following table is the list of valid file names and how they are processed:

Target media	Accepted filenames	Description

SD Card	`/sdimage.tar.xz` `/sdimage.tar.bz2` `/sdimage.tar.gz` `/sdimage.tar`	Tar of the filesystem. This will repartition the SD card to a single partition and extract this tarball to the filesystem. If present, a file named `/md5sums.txt` in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This `md5sums.txt` file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
SD Card	`/sdimage.dd.xz` `/sdimage.dd.bz2` `/sdimage.dd.gz` `/sdimage.dd`	Disk image of the media. This will be written to the SD card block device directly. If present on the USB Image Replicator drive, a file named `/sdimage.dd.md5` will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.

eMMC	`/emmcimage.tar.xz` `/emmcimage.tar.bz2` `/emmcimage.tar.gz` `/emmcimage.tar`	Tar of the filesystem. This will repartition the eMMC to a single partition and extract this tarball to the filesystem. If present, a file named `/md5sums.txt` in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This `md5sums.txt` file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
eMMC	`/emmcimage.dd.xz` `/emmcimage.dd.bz2` `/emmcimage.dd.gz` `/emmcimage.dd`	Disk image of the media. This will be written to the eMMC block device directly. If present on the USB Image Replicator drive, a file named `/emmcimage.dd.md5` will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.

SATA	`/sataimage.tar.xz` `/sataimage.tar.bz2` `/sataimage.tar.gz` `/sataimage.tar`	Tar of the filesystem. This will repartition the first SATA drive with a single partition and extract this tarball to the filesystem. If present, a file named `/md5sums.txt` in the tarball will have its contents checked against the whole filesystem after the tarball is extracted. This `md5sums.txt` file is optional and can be omitted, but it must not be blank if present. This file is present in our official images and is created during image capture with the Image Replicator tool.
SATA	`/sataimage.dd.xz` `/sataimage.dd.bz2` `/sataimage.dd.gz` `/sataimage.dd`	Disk image of the media. This will be written to the first SATA block device directly. If present on the USB Image Replicator drive, a file named `/sataimage.dd.md5` will be used to verify the data written to the SD card against this checksum. This file is provided with our official images and is created during image capture with the Image Replicator tool.

U-Boot	`/u-boot.imx`	U-Boot binary blob. This will be written to the SPI flash. The `imx_type` variable of the new file and the existing U-Boot installation on SPI flash will be checked to ensure the file being written is compatible with the current CPU. If the file `/u-boot.imx.md5` is present on the USB drive, this will be used to verify the data written to SPI flash.

Note:

SATA is only present on models with Dual/Quad CPUs on compatible Baseboards with SATA

Building the Image Replicator from Source

The Image Replicator tool uses Buildroot to create the bootable USB disk image and tarball. See the project repository on github for information on compatibility and instructions on building: https://github.com/embeddedTS/buildroot-ts

MicroSD Card

Note:

Our Image Replicator tool can be used to automate this process.

These instructions assume you have an SD card with one partition. Most SD cards ship this way by default. If the card has had its partition table modified this can be corrected with a tool like 'gparted' or 'fdisk'.

Plug the SD card into a USB reader and connect it to a linux workstation PC. Newer distributions include a utility called 'lsblk' which lists all block devices like a USB SD card reader:

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.

After plugging in the device after Linux has booted you can use dmesg to print out the kernel log. When the USB drive is added it will append to the end of that file. Try running:

dmesg | tail -n 100

 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)

Make sure the partition table is using the MBR scheme and not GPT.

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.

The following commands will reformat the first partition of the SD card, and unpack the latest filesystem on there:

# Verify nothing else has this mounted
sudo umount /dev/sdX1

sudo mkfs.ext3 /dev/sdX1
sudo mkdir /mnt/sd
sudo mount /dev/sdX1 /mnt/sd/
wget https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-bullseye-latest.tar.bz2

sudo tar --numeric-owner -xf debian-armhf-bullseye-latest.tar.bz2 -C /mnt/sd
sudo umount /mnt/sd
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. Reinsert the disk to flush the block cache completely, then run the following commands:

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

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

eMMC

Note:

Our Image Replicator tool can be used to automate this process.

Write the image:

These commands assume the unit is booted from SD and eMMC is set up with a single partition:

# Verify nothing else has this mounted
umount /dev/mmcblk2p1

mkfs.ext3 /dev/mmcblk2p1
mkdir /mnt/emmc
mount /dev/mmcblk2p1 /mnt/emmc
wget https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/distributions/debian/debian-armhf-bullseye-latest.tar.bz2
tar --numeric-owner -xf debian-armhf-bullseye-latest.tar.bz2 -C /mnt/emmc
umount /mnt/emmc
sync

Note:

The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3.

After the tarball is unpacked, the data on disk can be verified with md5sum:

# Drop any block cache
echo 3 > /proc/sys/vm/drop_caches
mount /dev/mmcblk2p1 /mnt/emmc
cd /mnt/emmc/
sudo md5sum -c md5sums.txt
umount /mnt/emmc
sync

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

Backup the image:

First boot the device to any compatible bootable SD card. The SD needs have enough free space for the compressed image of the data on the eMMC. Our default image eMMC image is ~500MB when compressed. A tarball of the eMMC can be created on the SD card with the following commands:

mkdir /mnt/emmc/
mount /dev/mmcblk2p1 /mnt/emmc/
cd /mnt/emmc/
tar --numeric-owner -cjf /root/emmc-backup.tar.bz2 *
cd /
umount /mnt/emmc/

Compile the Kernel

To add additional driver support, reduce the size of our stock kernel kernel, or to write custom kernel drivers the kernel can be compiled from our sources. The following steps walk through the kernel build process; they are compatible with most of our Linux distributions.

This device has multiple kernels released and available in our git repository:

Newer kernels are released on the linux-tsimx repository:

embeddedTS/linux-tsimx
The "ts-imx_4.9.11_1.0.0_ga" branch is the only one that should be used with our i.MX6 series.

For legacy kernels:

embeddedTS/linux-3.10.17-imx6
The "master" branch is 3.10.17 and is largely outdated and replaced with later kernels. This is used with the old Yocto Dora builds.
The "imx_3.10.53_1.1.0_ga" kernel is a stable branch. Use this with Yocto Dizzy, Fido, or compatible with Debian Jessie.
The "imx_3.14.52_1.1.0_ga" branch is compatible with Yocto Jethro, and Debian.
The "imx_4.1.15_1.0.0_ga" branch is compatible with Yocto Jethro, Yocto Morty and Debian. Includes recent fixes not in older branches. This is recommended for most users.

The kernel can be rebuilt by cross compiling from an x86 or x86_64 Linux workstation. Our stock kernels are built with the toolchains built by Yocto. The appropriate cross toolchain for your Linux workstation can be downloaded here:

x86_64
i686

Note:

Older kernels will require older toolchains. For older Yocto kernels use a matching Yocto toolchain. For Debian, the latest toolchain and kernel is recommended.

chmod a+x poky*.sh
sudo ./poky*.sh

This will ask for the install directory for the toolchain. A custom location can be chosen, however the following instructions will assume the default installation location.

This process will also require several applications for the install/build process. These can be installed on an Ubuntu/Debian workstation with the following command:

sudo apt-get install git build-essential lzop u-boot-tools libncursesw5-dev fakeroot bc

Once those are installed:

git clone https://github.com/embeddedTS/linux-tsimx.git -b ts-imx_4.9.11_1.0.0_ga linux-tsimx6 --depth 1

# For legacy kernels instead:
# git clone https://github.com/embeddedTS/linux-3.10.17-imx6.git -b imx_4.1.15_1.0.0_ga linux-tsimx6 --depth 1
# If it is already cloned, the "git pull" command will download and merge the latest changes

# For WiFi support, download qcacld-2.0:
# This is only compatible with 4.1.15 or 4.9.11 kernels
git clone https://github.com/embeddedTS/qcacld-2.0.git -b caf-wlan/CNSS.LEA.NRT_3.1

cd linux-tsimx6
# These export commands must be run every time before any make commands
export ARCH=arm
# For 64-bit
export CROSS_COMPILE=/opt/poky/2.2.2/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-
# For 32-bit
#export CROSS_COMPILE=/opt/poky/2.2.2/sysroots/i686-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-
export LOADADDR=0x10008000
export TEMPDIR=$(mktemp -d)

make ts4900_defconfig

## Make any changes in "make menuconfig" or driver modifications, then compile
make -j8 all uImage zImage

mkdir "$TEMPDIR"/boot/
cp arch/arm/boot/uImage  "$TEMPDIR"/boot/uImage
cp arch/arm/boot/zImage  "$TEMPDIR"/boot/zImage
cp arch/arm/boot/dts/imx6*-ts*.dtb "$TEMPDIR"/boot/
INSTALL_MOD_PATH="$TEMPDIR" make modules_install
make headers_install INSTALL_HDR_PATH="$TEMPDIR"

# Compile wifi driver:
cd ../qcacld-2.0/
export KERNEL_SRC="../linux-tsimx6/"
make clean
CONFIG_CLD_HL_SDIO_CORE=y make -j8
INSTALL_MOD_PATH="$TEMPDIR" make modules_install 

fakeroot sh -c "chmod 755 $TEMPDIR;
	chown -R root:root $TEMPDIR;
	tar cjvf kernel.tar.bz2 -C $TEMPDIR .;
	rm -rvf $TEMPDIR"

This will generate "kernel.tar.bz2" which contains the kernel and necessary modules. It can be installed to the device by copying it to a running unit and executing:

# Only run this on a device! Not on a workstation!
tar -xf kernel.tar.bz2 -C /

This can also be extracted over existing images from a workstation, or removable media like SD cards. For example, assuming the SD card on a workstation is "/dev/sdc":

mkdir /mnt/sd/
mount /dev/sdc1 /mnt/sd/
tar -xf kernel.tar.bz2 -C /mnt/sd/
umount /mnt/sd/

Change Kernel Splash Screen

The kernel splashscreen allow for a 224 color image, up to the full screen resolution. For the fastest boot speed, it should be kept as small as possible. The image will be centered around a black background.

To convert an image, for example, "mylogo.png":

convert mylogo.png mylogo.ppm
ppmquant 224 mylogo.ppm > mylogo-224.ppm
pnmnoraw mylogo-224.ppm > logo_user_clut224.ppm
cp logo_user_clut224.ppm <kernel build sources>/drivers/video/logo/

Recompile the kernel following the guide in the previous section to have the splashscreen appear on all future boots.

Add to the kernel cmdline in U-Boot, "logo.nologo" in order to completely disable the splash screen.

Linux 5.10.y

A compatible armhf cross compiler is needed for building the 5.10 kernel. We recommend using the cross compiler available in Debian distributions. It is also possible to use our Buildroot repository to build a compatible cross compiler.

Download and Configure

These steps assume a host Linux workstation with an appropriate cross compiler. While on most platforms the kernel can be downloaded, built, and installed all on the device, we recommend against this due to the amount of time, memory, and disk space that can be needed for a build.

Prerequisites

If using our instructions for using Docker to handle the cross compiler, then the Docker environment needs to be entered first:

# Create a place to store the kernel:
mkdir -p ~/Projects/tsimx6/kernel/
cd ~/Projects/tsimx6/kernel/
docker run -it --volume $(pwd):/work armhf-bullseye-toolchain bash

# Once in the Docker container shell, run:
cd /work/

If the Docker container is not being used, a number of host tools are required to be installed on the workstation:

# Install dependencies for kernel build
# The following command is for Ubuntu / Debian workstations. If using a different
# distribution, please consult distribution docs for the proper commands to install
# new packages/tools/libraries/etc.
apt-get install git fakeroot build-essential ncurses-dev xz-utils libssl-dev bc flex libelf-dev bison

Note:

The above prerequisite libraries and tools may not be the complete list, depending on the workstation's distribution and age. It may be necessary to install additional packages to support kernel compilation.

Download kernel repo on a host Linux workstation:

# Do a shallow clone of the sources
git clone --depth 1 -b linux-5.10.y https://github.com/embeddedTS/linux-lts

cd linux-lts/

Configure environment variables needed for building. This specifies the architecture, the cross compiler that is being used, the U-Boot kernel address, and to set up building the kernel modules for the WILC3000 Wi-Fi/BLE module:

export CROSS_COMPILE=arm-linux-gnueabihf-  # This may be different if using a different compiler!
export ARCH=arm
export LOADADDR=0x10008000
export WILC=y

The WILC3000 Wi-Fi/BLE drivers are maintained and built externally out of the kernel tree. Clone this tree inside of the linux-lts/ directory (this is built later):

git clone -b linux4microchip-2021.10-1 https://github.com/embeddedTS/wilc3000-external-module/

Next, set the default configuration for this platform. Note that a minimal defconfig and a full-feature defconfig are available. The minimal defconfig contains options for supporting the device and a few common peripherals and technologies. While the full defconfig includes much more support for things like USB devices, a more broad range of netfilter/iptables filter module support, etc.

make tsimx6_defconfig

# The minimal defconfig can alternately be used with:
# make tsimx6_minimal_defconfig

Build and Install

Note: If using the Docker container to cross compile, be sure to exit the container after the build script below completes! The tarball will be located in the linux-lts/ folder that was created.

The following will build the kernel and modules, and install the kernel, modules, and headers to a folder and create a tarball from that. This tarball can be unpacked to bootable media, e.g. microSD, eMMC, USB, etc., to update an existing bootable disk.

The script below is most easily saved as a text file and run from the command line as a script. Most terminal emulators will accept the whole script copy/pasted in to the terminal. But it is also possible to copy paste each line of text in to a terminal. In any case, the following is an example of how to compile the kernel. The script or commands used can be modified as needed to suit a specific build pipeline.

The script assumes the following environment variables are set before it is run. See the above sections for what these variables should be set to for this specific platform.

ARCH: Used to indicate the target CPU architecture.
CROSS_COMPILE: Used to point to an appropriate cross toolchain for the target platform.
LOADADDR [Optional]: Used on some platforms to tell U-Boot where to load the file.
WILC [Optional]: Set to "y" to build and install the WILC3000 Wi-Fi/BLE external modules.

#!/bin/bash -e

# Always build zImage, most common. If LOADADDR is set, then uImage is also built
TARGETS="zImage"
if [ -n "${LOADADDR}" ]; then TARGETS+=" uImage"; fi

# Build the actual kernel, binary files, and loadable modules.
# Use as many CPUs to do this as possible.
make -j"$(nproc)" && make ${TARGETS} && make modules

# Create a temporary directory to install the kernel to in order to use that as a base directory for a tarball.
# Also creates a temporary file that is used as the tarball name.
TEMPDIR=$(mktemp -d)
TEMPFILE=$(mktemp)
mkdir "${TEMPDIR}/boot/"

# Adds "arch/arm/boot/" path prefix to each TARGET
cp $(for i in ${TARGETS}; do echo arch/arm/boot/$i; done) "${TEMPDIR}"/boot/

# Copy the full .config file to the target, this is optional and can be removed
cp .config "${TEMPDIR}"/boot/config

# Copy all of the generated FDT binary files to the target
find arch/arm/boot/dts -name "*ts*.dtb" -exec cp {} "${TEMPDIR}/boot" \;

# Install kernel modules to the target
INSTALL_MOD_PATH="${TEMPDIR}" make modules_install

# Install kernel headers to the target, this is optional in most cases and can be removed to save space on the target
make headers_install INSTALL_HDR_PATH="${TEMPDIR}"

# If WILC is set to "y", then build the external module for the WILC300 Wi-Fi/BLE device.
# Note that this expects the source to be available as a subfolder in the kernel. See the above sections 
# for details on getting the driver source if it is used on this specific platform.
if [ "${WILC}" == "y" ]; then
    CONFIG_WILC_SPI=m INSTALL_MOD_PATH="${TEMPDIR}" make M=wilc3000-external-module modules modules_install
fi

# Use fakeroot to properly set permissions on the target folder as well as create a tarball from this.
fakeroot sh -c "chmod 755 ${TEMPDIR};
        chown -R root:root ${TEMPDIR};
        tar czf ${TEMPFILE}.tar.gz -C ${TEMPDIR} .";

# Create a final output tarball and cleanup all of the temporary files and folder.
cp ${TEMPFILE}.tar.gz embeddedTS-linux-lts-"$(date +"%Y%m%d")"-"$(git describe --abbrev=8 --dirty --always)".tar.gz
rm -rf "${TEMPDIR}" "${TEMPFILE}"

At this point, the tarball can be unpacked to a bootable media for the device. This can be done from a booted device, or by mounting removable media from a host Linux workstation. For example, if the root folder of the target filesystem to be updated is mounted to /mnt/, the following can be used to unpack the above tarball:

# Ensure the target filesystem is mounted to /mnt first!

# Extract kernel tarball to target filesystem, 
tar xhf embeddedTS-linux-lts-*.tar.gz -C /mnt

Note: The h argument to tar is necessary on recent distributions that use paths with symlinks. Not using it can potentially render the whole filesystem no longer bootable.

This will correctly unpack the kernel, modules, and headers to the target filesystem which can then be booted as normal.

Linux 6.6.y

A compatible armhf cross compiler is needed for building the 6.6 kernel. We recommend using the cross compiler available in Debian distributions. It is also possible to use our Buildroot repository to build a compatible cross compiler.

Download and Configure

These steps assume a host Linux workstation with an appropriate cross compiler. While on most platforms the kernel can be downloaded, built, and installed all on the device, we recommend against this due to the amount of time, memory, and disk space that can be needed for a build.

Prerequisites

If using our instructions for using Docker to handle the cross compiler, then the Docker environment needs to be entered first:

# Create a place to store the kernel:
mkdir -p ~/Projects/tsimx6/kernel/
cd ~/Projects/tsimx6/kernel/
docker run -it --volume $(pwd):/work armhf-bullseye-toolchain bash

# Once in the Docker container shell, run:
cd /work/

If the Docker container is not being used, a number of host tools are required to be installed on the workstation:

# Install dependencies for kernel build
# The following command is for Ubuntu / Debian workstations. If using a different
# distribution, please consult distribution docs for the proper commands to install
# new packages/tools/libraries/etc.
apt-get install git fakeroot build-essential ncurses-dev xz-utils libssl-dev bc flex libelf-dev bison

Note:

The above prerequisite libraries and tools may not be the complete list, depending on the workstation's distribution and age. It may be necessary to install additional packages to support kernel compilation.

Download kernel repo on a host Linux workstation:

# Do a shallow clone of the sources
git clone --depth 1 -b linux-6.6.y https://github.com/embeddedTS/linux-lts

cd linux-lts/

Configure environment variables needed for building. This specifies the architecture, the cross compiler that is being used, the U-Boot kernel address, and to set up building the kernel modules for the WILC3000 Wi-Fi/BLE module:

export CROSS_COMPILE=arm-linux-gnueabihf-  # This may be different if using a different compiler!
export ARCH=arm
export LOADADDR=0x10008000
export WILC=y

The WILC3000 Wi-Fi/BLE drivers are maintained and built externally out of the kernel tree. Clone this tree inside of the linux-lts/ directory (this is built later):

git clone -b linux4microchip-2024.04 https://github.com/embeddedTS/wilc3000-external-module/

Next, set the default configuration for this platform. Note that a minimal defconfig and a full-feature defconfig are available. The minimal defconfig contains options for supporting the device and a few common peripherals and technologies. While the full defconfig includes much more support for things like USB devices, a more broad range of netfilter/iptables filter module support, etc.

make tsimx6_defconfig

# The minimal defconfig can alternately be used with:
# make tsimx6_minimal_defconfig

Build and Install

Note: If using the Docker container to cross compile, be sure to exit the container after the build script below completes! The tarball will be located in the linux-lts/ folder that was created.

The following will build the kernel and modules, and install the kernel, modules, and headers to a folder and create a tarball from that. This tarball can be unpacked to bootable media, e.g. microSD, eMMC, USB, etc., to update an existing bootable disk.

The script below is most easily saved as a text file and run from the command line as a script. Most terminal emulators will accept the whole script copy/pasted in to the terminal. But it is also possible to copy paste each line of text in to a terminal. In any case, the following is an example of how to compile the kernel. The script or commands used can be modified as needed to suit a specific build pipeline.

The script assumes the following environment variables are set before it is run. See the above sections for what these variables should be set to for this specific platform.

ARCH: Used to indicate the target CPU architecture.
CROSS_COMPILE: Used to point to an appropriate cross toolchain for the target platform.
LOADADDR [Optional]: Used on some platforms to tell U-Boot where to load the file.
WILC [Optional]: Set to "y" to build and install the WILC3000 Wi-Fi/BLE external modules.

#!/bin/bash -e

# Always build zImage, most common. If LOADADDR is set, then uImage is also built
TARGETS="zImage"
if [ -n "${LOADADDR}" ]; then TARGETS+=" uImage"; fi

# Build the actual kernel, binary files, and loadable modules.
# Use as many CPUs to do this as possible.
make -j"$(nproc)" && make ${TARGETS} && make modules

# Create a temporary directory to install the kernel to in order to use that as a base directory for a tarball.
# Also creates a temporary file that is used as the tarball name.
TEMPDIR=$(mktemp -d)
TEMPFILE=$(mktemp)
mkdir "${TEMPDIR}/boot/"

# Adds "arch/arm/boot/" path prefix to each TARGET
cp $(for i in ${TARGETS}; do echo arch/arm/boot/$i; done) "${TEMPDIR}"/boot/

# Copy the full .config file to the target, this is optional and can be removed
cp .config "${TEMPDIR}"/boot/config

# Copy all of the generated FDT binary files to the target
find arch/arm/boot/dts -name "*ts*.dtb" -exec cp {} "${TEMPDIR}/boot" \;

# Install kernel modules to the target
INSTALL_MOD_PATH="${TEMPDIR}" make modules_install

# Install kernel headers to the target, this is optional in most cases and can be removed to save space on the target
make headers_install INSTALL_HDR_PATH="${TEMPDIR}"

# If WILC is set to "y", then build the external module for the WILC300 Wi-Fi/BLE device.
# Note that this expects the source to be available as a subfolder in the kernel. See the above sections 
# for details on getting the driver source if it is used on this specific platform.
if [ "${WILC}" == "y" ]; then
    CONFIG_WILC_SPI=m INSTALL_MOD_PATH="${TEMPDIR}" make M=wilc3000-external-module modules modules_install
fi

# Use fakeroot to properly set permissions on the target folder as well as create a tarball from this.
fakeroot sh -c "chmod 755 ${TEMPDIR};
        chown -R root:root ${TEMPDIR};
        tar czf ${TEMPFILE}.tar.gz -C ${TEMPDIR} .";

# Create a final output tarball and cleanup all of the temporary files and folder.
cp ${TEMPFILE}.tar.gz embeddedTS-linux-lts-"$(date +"%Y%m%d")"-"$(git describe --abbrev=8 --dirty --always)".tar.gz
rm -rf "${TEMPDIR}" "${TEMPFILE}"

At this point, the tarball can be unpacked to a bootable media for the device. This can be done from a booted device, or by mounting removable media from a host Linux workstation. For example, if the root folder of the target filesystem to be updated is mounted to /mnt/, the following can be used to unpack the above tarball:

# Ensure the target filesystem is mounted to /mnt first!

# Extract kernel tarball to target filesystem, 
tar xhf embeddedTS-linux-lts-*.tar.gz -C /mnt

Note: The h argument to tar is necessary on recent distributions that use paths with symlinks. Not using it can potentially render the whole filesystem no longer bootable.

This will correctly unpack the kernel, modules, and headers to the target filesystem which can then be booted as normal.

Features

Baseboard ID

All of our off the shelf baseboards contain a hard-wired 8-input multiplexer to indicate the baseboard model. This is not required to implement in custom baseboards, but it can be useful to identify the board model in software. The baseboard model is determined in the bootloader and the proper device tree is selected for the respective baseboard. For the TS-TPC-8390-4900 with a quad core cpu, this would load imx6q-ts4900-2.dtb. A solo TS-4900 on a TS-TPC-8950 woudl be imx6dl-ts4900-14.dtb. In u-boot the device tree ids are specified in hex, so 0x14 will match device tree 20. If a board does not have a specific device tree, it will fall back to the TS-8550 device tree which is imx6{q,dl}-ts4900.dtb. The TS-8550 itself does not have a device tree at imx6{q,dl}-ts4900-13.dtb.

4 DIO pins are used to obtain the baseboard model ID. The red LED (CN2_06), green LED (CN2_08), BUS_DIR (CN1_98), and BD_ID_DATA (CN1_83) are used for this purpose. All of these IO pins can be used normally outside of acquiring the ID number.

The 6 least significant input pins (Y0 - Y5) are used to define the baseboard model. The upper two inputs (Y6 and Y7) define board revision.

For custom baseboards we have reserved the address 42 which will never be used by our standard products.

TS-8160 baseboard ID resulting in ID 6, rev 0.

TS-Baseboard IDs
ID	Baseboard
0	TS-8200
1	Reserved, do not use
2	TS-TPC-8390
4	TS-8500
5	TS-8400
6	TS-8160
7	TS-8100
8	TS-8820-BOX
9	TS-8150
10	TS-TPC-8900
11	TS-8290
13	TS-8700
14	TS-8280
15	TS-8380
16	TS-AN20
17	TS-TPC-8920
19	TS-8550
20	TS-TPC-8950
22	TS-8551
42	Reserved for customer use, never used by us
63	TS-8200

Bluetooth

On the REV E TS-4900s the end of life TIWI-BLE module has been replaced with the Silex SX-SDMAC2832S+.

SILEX Bluetooth

Support for Bluetooth is provided by the BlueZ project. BlueZ has support for many different profiles for HID, A2DP, and many more. Refer to the BlueZ documentation for more information. Please see our BLE Examples page for information on installing the latest BlueZ release, getting started, and using demo applications.

First load the driver in bluez. For 5.10 and later, run:

btattach -P qca -S 115200 -B /dev/ttymxc1 &

For kernel 4.9 and below, run:

echo 27 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio27/direction
sleep .5
echo high > /sys/class/gpio/gpio27/direction
hciattach /dev/ttymxc1 qca 115200 -t30 flow

Either will create an hci0 interface that can interface with bluez. For example, to scan devices use blutoothctl commands power on and scan on.

root@tsimx6:~# bluetoothctl
Agent registered
[CHG] Controller 84:25:3F:B6:1C:4D Pairable: yes
[bluetooth]# power on
Changing power on succeeded
[bluetooth]# scan on
Discovery started
[CHG] Controller 84:25:3F:B6:1C:4D Discovering: yes
[NEW] Device 19:CD:41:6B:AC:09 19-CD-41-6B-AC-09

TI Bluetooth

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

To connect this to 'bluez' the Bluetooth device needs to be initialized and set up. The "BT_EN" pin needs to be pulsed, then 'hciattach' is used to connect to the device and set it up as an HCI interface:

# Install bluez if it is not already present
apt-get update
apt-get install bluez bluez-tools

# Loads firmware for the wifi+BT module
ifconfig wlan0 up

echo 237 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio237/direction
echo high > /sys/class/gpio/gpio237/direction
sleep .1
hciattach /dev/ttymxc1 texas 3000000
hciconfig hci0 up

Once this is loaded, it is possible to scan for nearby devices:

hcitool scan

This will return a list of devices such as:

	14:74:11:A1:1E:C9	BlackBerry 8530

Bluez has support for many different profiles for HID, A2DP, and many more. Refer to the Bluez documentation for more information.

CAN

The i.MX6 includes 2 CAN controllers which support the SocketCAN interface. Before proceeding with the examples, see the Kernel's CAN documentation here.

This board comes preinstalled with can-utils. These can be used to communicate over a CAN network without writing any code. The candump utility can be used to dump all data on the network

## First, set the baud rate and bring up the device:
ip link set can0 type can bitrate 250000
ip link set can0 up

## Dump data & errors:
candump can0 &

## Send the packet with:
#can_id = 0x7df
#data 0 = 0x3
#data 1 = 0x1
#data 2 = 0x0c
cansend can0 -i 0x7Df 0x3 0x1 0x0c
## Some versions of cansend use a different syntax.  If the above
## commands gives an error, try this instead:
#cansend can0 7DF#03010C

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

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

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

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

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

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

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

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

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

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

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

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

ip link set can0 type can restart-ms 100

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

COM (UART) Ports

This board uses UARTs from both the CPU and the FPGA. The CPU UART 0 (/dev/ttymxc0) is a dedicated console for Linux and U-Boot and not suggested to be reused. The other CPU UARTs for ttymxc1 through ttymxc4 are usable for end applications. These support up to 5Mb/s UART data with DMA.

The FPGA also emulates a MAX3100 UART interface accessible at /dev/ttyMAX0-2. These UARTs support a total throughput of about 115200^[1]. These UARTs include hardware that makes implementing RS-485 half duplex software extremely simple. If higher throughput is needed, the FPGA crossbar can be adjusted to use a CPU UART with TXEN support instead.

Note:

Our SPI interface matches the max3100 almost entirely, except optionally a single 8-bit transaction can be sent to act as a chip select between the three uarts supported on our interface. The default FPGA supports 3 UARTs on this interface. This is handled automatically by our driver (max3100-ts).

The RS-485 half duplex direction control is built into the ttyMAX UARTs. By default, they are connected to the RS-485 ports and no code is required for the transmit enable to toggle. The CPU UARTs however do not have transmit enable built in. The FPGA provides support for transmit enable on ttymxc1/ttymxc3, but additional setup steps are required so the FPGA can properly time the transmit enable output. The FPGA needs to know the baud rate, and symbol size (data bits, parity, stop bits) that the UART will be run at

For example:

# Configure ttymxc1 and ttymxc3 as 115200, 8n1

stty -F /dev/ttymxc1 115200 cs8 -cstopb
tshwctl --autotxen 1

stty -F /dev/ttymxc3 115200 cs8 -cstopb
tshwctl --autotxen 3

The 'tshwctl' tool will read the UART settings and set up the FPGA timing for TXEN automatically. The baud rate and mode settings must be set before running the 'tshwctl' command!

When using the FPGA for either the ttyMAX UARTs or the CPU UARTs, the TXEN timing will happen well under a single bit time ^[2] of any baud rate possible by the hardware.

All of these UARTs are accessed using the standard /dev/ interfaces. See these resources for information on programming with UARTs in Linux.

↑ Idle periods do not count towards the total throughput limitation.
↑ This is a requirement for half duplex MODBUS

The #FPGA includes a crossbar to select where UARTs are routed so these can be changed, but these are the default mappings:

UART	TX	RX	TXEN
ttymxc0	CN2_93	CN2_95	N/A
ttymxc1	Onboard Bluetooth RX	Onboard Bluetooth TX	N/A
ttymxc2	CN2_82	CN2_84	N/A
ttymxc3	CN2_86	CN2_88	N/A
ttymxc4	CN2_90	CN2_92	N/A
ttyMAX0	CN2-78	CN2-80	CN1-67
ttyMAX1	CN2-94	CN2-96	CN1-63
ttyMAX2	CN2-98	CN2-100	N/A

CPU

The i.MX6 is an armv7a Cortex-A9 by NXP. The CPU itself is available in 792MHz, 996MHz, and 1.2GHz with a solo, dual, or quad core processor.

Refer to NXP's documentation for in depth documentation on these CPU cores:

Device Tree Order

On startup U-boot can load several device trees to attempt to find the right matching device tree. By default, it will load in this order:

If the board is a REV E or later:

   imx6<cpu>-ts4900-reve-<baseboard id>.dtb
   imx6<cpu>-ts4900-reve.dtb
   imx6<cpu>-ts4900-<baseboard id>.dtb
   imx6<cpu>-ts4900.dtb

If the board is REV D or earlier:

   imx6<cpu>-ts4900-<baseboard id>.dtb
   imx6<cpu>-ts4900.dtb

For example, on a Quad core i.MX6 REV E TS-4900 on a TS-TPC-8390, this will attempt to load these files:

   imx6q-ts4900-reve-2.dtb
   imx6q-ts4900-reve.dtb
   imx6q-ts4900-2.dtb
   imx6q-ts4900.dtb

The last device tree in the list is a "fallback" device tree that exposes most basic functionality. On the development TS-8550 board, this will intentionally fall back to this device tree.

In the kernel sources, the device tree source files are found in arch/arm/boot/dts/. The majority of the devices are found in: imx6qdl-ts4900.dtsi and imx6qdl-ts4900-reve.dtsi. For custom baseboards it will be simplest to modify these dtsi files directly.

eMMC

This board includes a Micron eMMC module with builds that have "4096F" in the part number. Our off the shelf builds are 4GiB, but up to 64GiB are available for larger builds. The eMMC flash appears to Linux as an SD card at /dev/mmcblk2. Our default programming will include one partition programmed with our Yocto image.

The eMMC are like SD cards in that they should not be powered down during a write/erase cycle. This eMMC module includes support for setting a fuse for a "Write Reliability" mode, and a "pseudo-SLC" mode. With both of these enabled then any writes will be atomic to 512B. If a sector is being written during a power loss, a block is guaranteed to have either the old or new data. This scheme is far more resilient to power loss than more traditional flash media. In cases of old 512B data fsck will still be able to recover a mountable filesystem. In cases where the corrupted file is a database it can still need a mechanism for recovery.

When this pSLC mode is turned on it will reduce the available space to under half, and reduce the write speed.

See our post on preventing filesystem corruption.

The mmc-utils package is used to enable these modes. First determine the exact size of the flash you're using:

mmc extcsd read /dev/mmcblk2 | grep MAX_ENH_SIZE_MULT -A 1

Max Enhanced Area Size [MAX_ENH_SIZE_MULT]: 0x0001cd
 i.e. 1888256 KiB

So in this case, 1888256 KiB (1.801 GiB) is the max size of the enhanced partition.

MAX_ENH_SIZE=$(mmc extcsd read /dev/mmcblk2 | grep "\\[MAX_ENH_SIZE_MULT\\]" -A 1 | sed -n '2p' | cut -f 3 -d ' ')
mmc write_reliability set -n 0 /dev/mmcblk2
# If write_reliability fails with "WR_REL_SET is read-only", this can be ignored. Many newer 
# eMMC chipsets ship with write reliability always on

mmc enh_area set -y 0 "$MAX_ENH_SIZE" /dev/mmcblk2

WARNING:

Setting either of those modes is permanent. Using the wrong value it is possible to brick eMMC which will not be covered by the warranty. Evaluation units with fuses set will not be accepted through returns.

After this is run, cycle power to the board. On all future boots the eMMC will be detected at the smaller size. Changing the enhanced area will erase the drive. After these mmc commands the disk will need to be rewritten.

This can be applied automatically from our USB production blast.sh with:

#!/bin/bash

mmc extcsd read /dev/mmcblk2 > /tmp/csd
PART_DONE=$(grep PARTITION_SETTING_COMPLETED < /tmp/csd | cut -f 2 -d ':' | tr -d '[:space:]')
if [ "$PART_DONE" = "0x00" ]; then
    WR_REL_SET=$(grep "\\[WR_REL_SET\\]" < /tmp/csd | cut -f 2 -d ':' | tr -d '[:space:]')
    MAX_ENH_SIZE=$(grep "\\[MAX_ENH_SIZE_MULT\\]" < /tmp/csd -A 1 | sed -n '2p' | cut -f 3 -d ' ')

    # Some eMMC devices ship with this enabled already
    if [ "$WR_REL_SET" = "0x00" ]; then
        mmc write_reliability set -n 0 /dev/mmcblk2
    fi
    mmc enh_area set -y 0 "$MAX_ENH_SIZE" /dev/mmcblk2
    # This requires a power cycle on the eMMC for these settings.  
    # This pokes a register in the FPGA to cause a real POR rather 
    # than software reset
    tshwctl --addr 30 --poke 0x2
else
    echo "Partitioning is completed!"
fi

Ethernet Port

The i.MX6 includes a 10/100/1000 Ethernet. In Linux this is the eth0 interface. The MAC address uses the Technologic Systems 00:d0:69:00:00:00, and the last 3 octets are assigned from our pool. The MAC address is burned into the CPU's fuses during production, and will be read back automatically by software in Linux or U-Boot. Each board is also assigned 1 additional sequential mac address which is used on some carrier boards that add a second ethernet.

Freescale has a published erratum regarding the maximum Ethernet speed. The default kernel can achieve about 400 Mb/s.

Note:

Ethernet Magnetics should be placed as close to CN2 as possible on the base board.

FPGA

The Lattice ICE40 FPGA provides auto TX enable for RS-485 half duplex, a few more DIO, the UART MUX, and it can generate clocks for use on a baseboard. Most of these registers are controlled using tshwctl in the ts4900-utils repository. The DIO can be accessed using the sysfs GPIOs 224 to 255 using the "ts4900gpio" driver. See the #GPIO section for more information on the recommended GPIO access. The below examples will communicate directly over i2c.

Usage: tshwctl [OPTIONS] ...
Technologic Systems i.mx6 FPGA Utility
     -m, --addr <address>   Sets up the address for a peek/poke
     -v, --poke <value>     Writes the value to the specified address
     -t, --peek             Reads from the specified address
     -i, --mode <8n1>       Used with -a, sets mode like '8n1', '7e2', etc
     -x, --baud <speed>     Used with -a, sets baud rate for auto485
     -a, --autotxen <uart>  Enables autotxen for supported CPU UARTs
                              Uses baud/mode if set or reads the current
                              configuration of that uart
     -c, --dump             Prints out the crossbar configuration
     -g, --get              Print crossbar for use in eval
     -s, --set              Read environment for crossbar changes
     -q, --showall          Print all possible FPGA inputs and outputs.
     -h, --help             This message

On every poweron the FPGA is programmed using the file in /boot/ts4900-fpga.bin. U-boot copies this into memory, and runs the "ice40" command to reprogram the FPGA. Without this file the FPGA will not do anything. This FPGA interfaces to the i.MX6 using the first CPU I2C bus. You can use the "tshwctl --addr <addr>" with the "--peek" or "--poke <val>" to access these registers.

Addr	Bits	Function
00	7:3	CN1_63 Crossbar
	2	CN1_63 Input Data
	1	CN1_63 Output Data
	0	CN1_63 Output Enable
01	7:3	CN1_67 Crossbar
	2	CN1_67 Input Data
	1	CN1_67 Output Data
	0	CN1_67 Output Enable
02	7:3	CN1_87 Crossbar
	2	CN1_87 Input Data
	1	CN1_87 Output Data
	0	CN1_87 Output Enable
03	7:3	ttymxc3 rxd Crossbar
	2	ttymxc3 rxd Input Data
	1	ttymxc3 rxd Output Data
	0	ttymxc3 rxd Output Enable
04	7:3	ttymxc1 CTS Crossbar
	2	ttymxc1 CTS Input Data
	1	ttymxc1 CTS Output Data
	0	ttymxc1 CTS Output Enable
05	7:3	CN2_78 Crossbar
	2	CN2_78 Input Data
	1	CN2_78 Output Data
	0	CN2_78 Output Enable
06	7:3	CN2_80 Crossbar
	2	CN2_80 Input Data
	1	CN2_80 Output Data
	0	CN2_80 Output Enable
07	7:3	CN2_86 Crossbar
	2	CN2_86 Input Data
	1	CN2_86 Output Data
	0	CN2_86 Output Enable
08	7:3	CN2_88 Crossbar
	2	CN2_88 Input Data
	1	CN2_88 Output Data
	0	CN2_88 Output Enable
09	7:3	CN2_94 Crossbar
	2	CN2_94 Input Data
	1	CN2_94 Output Data
	0	CN2_94 Output Enable
10	7:3	CN2_96 Crossbar
	2	CN2_96 Input Data
	1	CN2_96 Output Data
	0	CN2_96 Output Enable
11	7:3	CN2_98 Crossbar
	2	CN2_98 Input Data
	1	CN2_98 Output Data
	0	CN2_98 Output Enable
12	7:3	CN2_100 Crossbar
	2	CN2_100 Input Data
	1	CN2_100 Output Data
	0	CN2_100 Output Enable
13	7:2	Reserved
	1	BT_EN Output Enable
	0	Reserved
14	7:2	Reserved
	1	WL_EN Output Enable
	0	Reserved
15	7:3	Reserved
	2	BT_RTS Input value
	1:0	Reserved
16	7:3	BT_CTS Crossbar
	2	BT_CTS Input value
	1	BT_CTS Output value
	0	BT_CTS Output Enable
17	7:3	BT_RXD Crossbar
17	2:0	Reserved
18	7:3	ttymxc1 RXD Crossbar
18	2:0	Reserved
29	7:2	Reserved
	1	Push sw reboot enable ^[1]
	0	Reserved
30	7:2	Reserved
	1	Reset (on 1)
	0	Reserved
31	7:3	Reserved
	2	Push SW Input value
	1:0	Reserved
32	7:0	RS485_CNT0 bits 23:16
33	7:0	RS485_CNT0 bits 15:8
34	7:0	RS485_CNT0 bits 7:0
35	7:0	RS485_CNT1 bits 23:16
36	7:0	RS485_CNT1 bits 15:8
37	7:0	RS485_CNT1 bits 7:0
38	7:0	RS485_CNT2 bits 23:16
39	7:0	RS485_CNT2 bits 15:8
40	7:0	RS485_CNT2 bits 7:0
41	7:0	RS485_CNT3 bits 23:16
42	7:0	RS485_CNT3 bits 15:8
43	7:0	RS485_CNT3 bits 7:0
44	7:3	SPIUART0 RX Crossbar
44	2:0	Reserved
45	7:3	SPIUART1 RX Crossbar
45	2:0	Reserved
46	7:3	SPIUART2 RX Crossbar
46	2:0	Reserved
51	7:4	FPGA Revision
	3	B1 Strapping input value
	2	G1 Strapping input value
	1	L14 Strapping input value
	0	N14 Strapping input value
53	7:3	SPIUART0 CTS Crossbar
53	2:0	Reserved
54	7:3	SPIUART1 CTS Crossbar
54	2:0	Reserved
55	7:3	SPIUART2 CTS Crossbar
55	2:0	Reserved

↑ Set 1 to enable hardware reset on PUSH_SW low

The FPGA crossbar allows almost any of the FPGA pins to be rerouted on the carrier board. All of the above registers that have a crossbar mux value can be written with these values to change the output value. When using the crossbar pins that are outputs, bit 1 should also be set to allow output enables.

Crossbar Value	Selected Function
0	Do not change
1	BT_RTS
2	BT_TXD
3	CN1_63
4	CN1_67
5	CN2_100
6	ttymxc1 RTS#
7	CN2_78
8	CN2_80
9	CN2_86
10	CN2_88
11	CN2_94
12	CN2_96
13	CN2_98
14	ttymxc3 TXD
15	ttymxc1 TXD
16	SPIUART0_TX
17	SPIUART0_TXEN
18	SPIUART0_RTS
19	SPIUART1_TX
20	SPIUART1_TXEN
21	SPIUART1_RTS
22	SPIUART2_TX
23	SPIUART2_TXEN
24	SPIUART2_RTS
25	ttymxc1 TXEN
26	ttymxc3 TXEN
27	12MHz clock
28	14MHz clock
29	24MHz clock
30	28.88MHz clock
31	GPIO

On startup these are the default values:

Pad	Default Mapping	FGPA Addr	Crossbar Reset Value
CN1_63	SPIUART1_TXEN	0	0xa1
CN1_67	SPIUART0_TXEN	1	0x89
CN1_87	GPIO 226	2	0xf8
ttymxc3 RXD	CN2_88	3	0x80
ttymxc1 CTS	BT_RTS	4	0x8
CN2_78	SPIUART0_TXD	5	0x81
CN2_80	GPIO ^[1]	6	0xf8
CN2_86	ttymxc3 txd	7	0x71
CN2_88	GPIO ^[2]	8	0xf8
CN2_94	SPIUART1_TXD	9	0x99
CN2_96	GPIO	10	0xf8
CN2_98	SPIUART2_TXD	11	0xb1
CN2_100	GPIO ^[3]	12	0xf8
BT_CTS	ttymxc1 RTS	16	0x31
BT_RXD	ttymxc1 TXD	17	0x78
ttymxc1 RXD	BT_TXD	18	0x10
SPIUART0 RX	CN2_80	44	0x40
SPIUART1 RX	CN2_96	45	0x60
SPIUART2 RX	CN2_100	46	0x28
SPIUART0 CTS	GPIO ^[4]	53	0xf8
SPIUART1 CTS	GPIO ^[5]	54	0xf8
SPIUART2 CTS	GPIO ^[6]	55	0xf8

↑ This pin is GPIO to just be used as an input for SPIUART0_RXD
↑ This pin is GPIO to just be used as an input for ttymxc3 rxd
↑ This pin is GPIO to just be used as an input for SPIUART2_RXD
↑ Route to GPIO to go nowhere
↑ Route to GPIO to go nowhere
↑ Route to GPIO to go nowhere

FPGA Crossbar

The FPGA crossbar allows adjusting the routing for pins without modifying the FPGA logic. This allows you reroute UARTs, and change pin functions.

List the default mappings with:

root@ts-imx6:~# tshwctl --get
CN1_63=TTYMAX1_TXEN
CN1_67=TTYMAX0_TXEN
CN1_87=GPIO
TTYMXC3_RXD=CN2_88
TTYMXC1_CTS=BT_RTS
CN2_78=TTYMAX0_TXD
CN2_80=GPIO
CN2_86=TTYMXC3_TXD
CN2_88=GPIO
CN2_94=TTYMAX1_TXD
CN2_96=GPIO
CN2_98=TTYMAX2_TXD
CN2_100=GPIO
BT_CTS=TTYMXC1_RTS
BT_RXD=TTYMXC1_TXD
TTYMXC1_RXD=BT_TXD
TTYMAX0_RXD=CN2_80
TTYMAX1_RXD=CN2_96
TTYMAX2_RXD=CN2_100
TTYMAX0_CTS=GPIO
TTYMAX1_CTS=GPIO
TTYMAX2_CTS=GPIO

The possible outputs can also be listed with "tshwctl --showall"

FPGA Outputs:
UNCHANGED
BT_RTS
BT_TXD
CN1_63
CN1_67
CN2_100
TTYMXC1_RTS
CN2_78
CN2_80
CN2_86
CN2_88
CN2_94
CN2_96
CN2_98
TTYMXC3_TXD
TTYMXC1_TXD
TTYMAX0_TXD
TTYMAX0_TXEN
TTYMAX0_RTS
TTYMAX1_TXD
TTYMAX1_TXEN
TTYMAX1_RTS
TTYMAX2_TXD
TTYMAX2_TXEN
TTYMAX2_RTS
TTYMXC1_TXEN
TTYMXC3_TXEN
CLK_12MHZ
CLK_14MHz
CLK_24MHz
CLK_28P88MHZ
GPIO

The --set option will read for any matching environment variables and make changes to the crossbar.

Route ttymxc1 from bluetooth to CN2_94-CN2_100.

export CN2_94=TTYMXC1_TXD
export TTYMXC1_RXD=CN2_96
export CN2_98=TTYMXC1_CTS
export CN2_100=TTYMXC1_RTS
tshwctl --set

Set up 24MHz clk on CN1_67:

export CN1_67=CLK_24MHz
tshwctl --set

Replace FPGA UART pins with CPU UARTs for higher throughput. For example, to switch around ttymxc1 / ttyMAX0, and ttymxc3 / ttyMAX1:

# Replace ttyMAX0 with ttymxc1 for RS485 which is BT uart by default
# leave bt uart disconnected since it cannot run with SPI uart
export CN1_67=TTYMXC1_TXEN
export TTYMXC1_RXD=CN2_80
export CN2_78=TTYMXC1_TXD

# Replace ttyMAX1 for second RS485 port
export CN1_63=TTYMXC3_TXEN
export TTYMXC3_RXD=CN2_96
export CN2_94=TTYMXC3_TXD

# Put ttyMAX1 on CN2_86/88 (replace ttymxc3)
export TTYMAX1_RXD=CN2_88
export CN2_86=TTYMAX1_TXD

# Apply all these changes
tshwctl --set

GPIO

Note:

It is possible to use memory mapped CPU registers as documented in the CPU reference manual to control GPIO. When using this, be aware that the kernel may attempt to also access these registers for various reasons. Also note that each register represents a bank of GPIO pins. Use a read-modify-write operation to avoid disturbing other GPIO pins. We strongly recommend using the sysfs interface as described below.

The i.MX6 GPIO are available using the kernel sysfs interface. See the kernel's documentation here for more detail. This interface provides a set of files and directories for interacting with GPIO. This allows GPIO to be accessed from any language that can read and write files. For example, to toggle CN1_89/EIM_A22, the kernel maps this to GPIO 48 (See the table below for the full I/O mapping).

To interact with this pin, first export it to userspace:

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

If the command returns with a permission denied on a GPIO that means it is claimed by another kernel driver. If it succeeds, the kernel will create the "/sys/class/gpio/gpio48/" directory. The relevant files in this directory are:

 direction - "in", "high", "low", or "out".  Out is equivalent to low
 value - write "1" or "0", or read "1" or "0" if direction is in
 edge - write with "rising", "falling", or "none"

# Set GPIO 48 high
echo "out" > /sys/class/gpio/gpio48/direction
echo "1" > /sys/class/gpio/gpio48/value
# Set GPIO 48 low
echo "0" > /sys/class/gpio/gpio48/value

# Read the value of GPIO 48
echo "in" > /sys/class/gpio/gpio48/direction
cat /sys/class/gpio/gpio48/value

As an output, the "value" file can be written with "0" for low (GND), or "1" for high (3.3V). As an input the GPIO will have a 100k pullup. The GPIO pins from the i.MX6 processor support an absolute maximum voltage range of -0.5 to 3.6V. It is also possible to use any processor GPIO as an interrupt. This is done by writing the "edge" file and using select() or poll() on the "value" file to watch for changes. See the Interrupts section for more details.

The GPIO numbers in the table below are relevant to how the Linux references these numbers. The CPU documentation refers to bank and IO while Linux flattens this out to one number space.

CPU PAD ^[1]	GPIO Number	Common Functions ^[2]	Location
SD4_DAT1	41	LCD_PWM^[3], #GPIO	CN1_57
KEY_COL2	106	CAN_1_TXD, #GPIO	CN2_97
KEY_ROW2	107	CAN_1_RXD, #GPIO	CN2_99
KEY_COL0	102	UART4_TXD	CN2_86, #FPGA Muxed
KEY_ROW0	103	UART4_RXD	CN2_88, #FPGA Muxed
KEY_COL1	104	UART5_TXD	CN2_90
KEY_ROW1	105	UART5_RXD	CN2_92
KEY_COL3	108	I2C_2_CLK	CN2_28
KEY_ROW3	109	I2C_2_DAT	CN2_30
KEY_COL4	110	CAN_2_TXD, #GPIO	CN1_71
KEY_ROW4	111	CAN_2_RXD, #GPIO	CN1_69
GPIO_0	0	AUD_MCLK	CN2_54
GPIO_1	1	USB_OTG_ID	CN2_74
GPIO_2	2	Red LED	Onboard
CSI0_DAT17 ^[4]	163	#GPIO	CN2_56
SD4_DAT7 ^[5]	47	#GPIO	CN2_58
GPIO_7	7	UART2_TXD	CN2_78, #FPGA Muxed
GPIO_8	8	UART2_RXD	CN2_80, #FPGA Muxed
SD3_RST ^[6]	200	#GPIO	CN2_60
GPIO_16	203	#GPIO	CN2_62
GPIO_17	204	#GPIO	CN2_64
GPIO_19	101	#GPIO	CN2_68
CSI0_MCLK	147	#GPIO	CN2_70
CSI0_PIXCLK	146	#GPIO	CN2_72
CSI0_DAT4	150	AUD_CLK, #GPIO	CN2_36
CSI0_DAT5	151	AUD_TXD, #GPIO	CN2_40
CSI0_DAT6	152	AUD_FRM, #GPIO	CN2_38
CSI0_DAT7	153	AUD_RXD, #GPIO	CN2_42
CSI0_DAT8	154	SPI_2_CLK	CN2_71
CSI0_DAT9	155	SPI_2_MOSI	CN2_67
CSI0_DAT10	156	SPI_2_MISO	CN2_69
CSI0_DAT11	157	SPI_2_CS#	CN2_65
CSI0_DAT12	158	#GPIO	CN2_52
CSI0_DAT13	159	#GPIO	CN2_66
DI0_DISP_CLK	112	LCD_CLK, #GPIO	CN1_49
DI0_PIN2	114	LCD_HSYNC, #GPIO	CN1_51
DI0_PIN3	115	LCD_VSYNC, #GPIO	CN1_53
DI0_PIN15	113	LCD_DE, #GPIO	CN1_55
DISP0_DAT0	117	LCD_D00, #GPIO	CN1_24
DISP0_DAT1	118	LCD_D01, #GPIO	CN1_26
DISP0_DAT2	119	LCD_D02, #GPIO	CN1_28
DISP0_DAT3	120	LCD_D03, #GPIO	CN1_30
DISP0_DAT4	121	LCD_D04, #GPIO	CN1_32
DISP0_DAT5	122	LCD_D05, #GPIO	CN1_34
DISP0_DAT6	123	LCD_D06, #GPIO	CN1_38
DISP0_DAT7	124	LCD_D07, #GPIO	CN1_40
DISP0_DAT8	125	LCD_D08, #GPIO	CN1_19
DISP0_DAT9	126	LCD_D09, #GPIO	CN1_21
DISP0_DAT10	127	LCD_D10, #GPIO	CN1_23
DISP0_DAT11	133	LCD_D11, #GPIO	CN1_25
DISP0_DAT12	134	LCD_D12, #GPIO	CN1_27
DISP0_DAT13	135	LCD_D13, #GPIO	CN1_31
DISP0_DAT14	136	LCD_D14, #GPIO	CN1_33
DISP0_DAT15	137	LCD_D15, #GPIO	CN1_35
DISP0_DAT16	138	LCD_D16, #GPIO	CN1_37
DISP0_DAT17	139	LCD_D17, #GPIO	CN1_39
DISP0_DAT18	140	LCD_D18, #GPIO	CN1_41
DISP0_DAT19	141	LCD_D19, #GPIO	CN1_43
DISP0_DAT20	142	LCD_D20, #GPIO	CN1_45
DISP0_DAT21	143	LCD_D21, #GPIO	CN1_42
DISP0_DAT22	144	LCD_D22, #GPIO	CN1_44
DISP0_DAT23	145	LCD_D23, #GPIO	CN1_46
EIM_LBA	59	#GPIO, BUS_ALE#	CN1_96
EIM_OE	57	#GPIO ^[7]	CN1_83
EIM_RW	58	#GPIO,BUS_DIR	CN1_98
EIM_CS0	55	#GPIO, BUS_CS#	CN1_100
EIM_CS1	56	Green LED	Onboard
EIM_A16	54	#GPIO EN_USB_5V ^[8]	CN1_04
EIM_A17	53	#GPIO OFF_BD_RESET# ^[9]	CN1_09
EIM_A18	52	#GPIO	CN1_81
EIM_A19	51	#GPIO EN_LCD_3.3V ^[10]	CN1_48
EIM_A20	50	#GPIO	CN1_85
EIM_A21	49	#GPIO	CN1_77
EIM_A22	48	#GPIO	CN1_89
EIM_A23	166	#GPIO	CN1_91
EIM_A24	132	#GPIO ^[7]	CN1_93
EIM_D16	80	SPI_1_CLK	CN1_60
EIM_D17	81	SPI_1_MISO	CN1_56
EIM_D18	82	SPI_1_MOSI	CN1_58
EIM_D19	83	SPI_1_CS# ^[11]	Onboard
EIM_D21	85	I2C_1_CLK ^[12]	Onboard
EIM_D28	92	I2C_1_DAT ^[12]	Onboard
EIM_D24	88	UART3_TXD	CN2_82
EIM_D25	89	UART3_RXD	CN2_84
EIM_EB1	61	BUS_BHE#, #GPIO	CN1_99
EIM_BCLK	191	#GPIO	CN1_79
EIM_WAIT	128	BUS_WAIT#, #GPIO ^[7]	CN1_97
EIM_D31	95	#GPIO	CN1_65
EIM_DA0	64	MUX_AD_00, #GPIO	CN1_94
EIM_DA1	65	MUX_AD_01, #GPIO	CN1_92
EIM_DA2	66	MUX_AD_02, #GPIO	CN1_90
EIM_DA3	67	MUX_AD_03, #GPIO	CN1_88
EIM_DA4	68	MUX_AD_04, #GPIO	CN1_86
EIM_DA5	69	MUX_AD_05, #GPIO	CN1_84
EIM_DA6	70	MUX_AD_06, #GPIO	CN1_82
EIM_DA7	71	MUX_AD_07, #GPIO	CN1_80
EIM_DA8	72	MUX_AD_08, #GPIO	CN1_78
EIM_DA9	73	MUX_AD_09, #GPIO	CN1_76
EIM_DA10	74	MUX_AD_10, #GPIO	CN1_74
EIM_DA11	75	MUX_AD_11, #GPIO	CN1_72
EIM_DA12	76	MUX_AD_12, #GPIO	CN1_70
EIM_DA13	77	MUX_AD_13, #GPIO	CN1_68
EIM_DA14	78	MUX_AD_14, #GPIO	CN1_66
EIM_DA15	79	MUX_AD_15, #GPIO	CN1_64

↑ The pad name does not often correspond with the functionality of the IO we use, but can be used to reference the pad in the CPU manual.
↑ This does not contain all of the functions possible for a pin, but the common functions as they are used on our off the shelf basebords. Consult the i.MX6 CPU Reference manual for a complete list.
↑ This pin is used to tune the LCD backlight through the PWM controller. On our baseboards where there is an LCD present this is connected to provide a sysfs tunable backlight. On other baseboards this is usable as a GPIO.
↑ This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #5, or pad "GPIO_5".
↑ This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #6, or pad "GPIO_6"
↑ This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #9, or pad "GPIO_9"
↑ ^7.0 ^7.1 ^7.2 This GPIO stays LOW when power is applied and defaults to a low state until modified by software
↑ On our off the shelf baseboards this pin typically controls the 5V rail for USB peripherals. For custom designs this can optionally be connected to a FET to control USB peripherals power.
↑ This pin is dedicated to resetting offboard peripherals during a full reboot.
↑ On our off the shelf baseboards this is normally used to toggle power to the LCD if the baseboard uses an LCD.
↑ Used for onboard flash
↑ ^12.0 ^12.1 Used for communication with RTC and FPGA

FPGA GPIO

The FPGA GPIO can also be accessed through the sysfs API. These are available at GPIOs 224 to 255. Not all of the reserved pins are used on this design, but they will be reserved by the kernel.

FPGA PAD	GPIO Number
CN1_63	224
CN1_67	225
CN1_87	226
CN1_64/MUX_AD_15 ^[1]	227
CN2_54 ^[1]	228
CN2_78	229
CN2_80	230
CN2_86	231
CN2_88	232
CN2_94	233
CN2_96	234
CN2_98	235
CN2_100	236
CN1_73/PUSH_SW	255

↑ ^1.0 ^1.1 This pin is not an FPGA pin on PCB revisions after A

I2S Audio

The TS-4900 supports an I2S output, but to be usable for most audio applications it must be connected to an audio codec. Our off the shelf baseboards use the Freescale SGTL5000 codec. This provides a standard alsa driver which most Linux applications will support.

For integrating audio into your application, gstreamer is in our default image and provides bindings for most common programming languages.

Gstreamer Web Site

The Yocto image includes several utilities which can be used to test gstreamer.

Interrupts

The i.MX6 CPU GPIO are also able to function as interrupts on rising and falling edges. This is accessible from the kernel as well as userspace. Userspace IRQs are exposed through the sysfs gpio mechanism. This example will trigger on a falling edge for GPIO 48:

echo "48" > /sys/class/gpio/export
echo "in" > /sys/class/gpio/gpio48/direction
echo "falling" > /sys/class/gpio/gpio48/edge

From here, an application can poll() or select() on the "/sys/class/gpio/gpio48/value" file and will return when the edge setting has been triggered:

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <sys/select.h>
#include <sys/stat.h>
#include <unistd.h>
 
int main(int argc, char **argv)
{
	char gpio_irq[64];
	int ret, irqfd = 0, i = 0;
	fd_set fds;
	FD_ZERO(&fds);
	int buf;
 
	if(argc < 2) {
		printf("Usage: %s <gpio number>\n", argv[0]);
		return 1;
	}
 
	snprintf(gpio_irq, sizeof(gpio_irq), "/sys/class/gpio/gpio%d/value", atoi(argv[1]));
	irqfd = open(gpio_irq, O_RDONLY, S_IREAD);
 
	if(irqfd == -1) {
		printf("Could not open IRQ %s\n", argv[1]);
		printf("Make sure the GPIO is already exported", argv[1]);
		return 1;
	}

	// Read first since there is always an initial status
	ret = read(irqfd, &buf, sizeof(buf));

	while(1) {
		FD_SET(irqfd, &fds);
		// See if the IRQ has any data available to read
		ret = select(irqfd + 1, NULL, NULL, &fds, NULL);
 
		if(FD_ISSET(irqfd, &fds))
		{
			FD_CLR(irqfd, &fds);  //Remove the filedes from set
			printf("IRQ detected %d\n", i);
			fflush(stdout);
			i++;
			
			/* The return value includes the actual GPIO register value */
			read(irqfd, &buf, sizeof(buf));
			lseek(irqfd, 0, SEEK_SET);
		}
 
		//Sleep, or do any other processing here
		usleep(100000);
	}
 
	return 0;
}

This example can be run as "./irqtest 48" which will echo every time the pin changes but not consume any CPU time while waiting for an edge to occur.

LCD Interface

The TS-4900 provides an RGB24 parallel display, and LVDS outputs. Most user applications access this using the toolkits like QT or GTK which write to /dev/fb0 to access the LCD. See this section for an example on user interface programming.

For custom baseboards using LCDs you will need to specify the LCD timing. The timing is added in drivers/video/mxc/mxc_lcdif.c. The mode string "OKAYA-WVGA" in this case is then referenced in your baseboard's device tree. See this example for the TS-TPC-8390 for the device tree block.

arch/arm/boot/dts/imx6qdl-ts4900-2.dtsi

See this section for further detail on which device tree file to use.

LVDS

The TS-4900 includes one LVDS output from the i.MX6 processor. This interface can provide a pixel clock up to 85MHz supporting displays up to 1366x768 at 60hz. The LVDS pairs are available on these pins:

Pin	Signal
LVDS CLK-	CN2_41
LVDS CLK+	CN2_43
LVDS TX0+	CN2_22
LVDS TX0-	CN2_24
LVDS TX1+	CN2_48
LVDS TX1-	CN2_46
LVDS TX2+	CN2_16
LVDS TX2-	CN2_18
LVDS TX3+	CN2_10
LVDS TX3-	CN2_12

After being connected the device tree in Linux will need to be created for your carrier board which will specify the LCD timing. See the file imx6qdl-ts4900-14.dtsi for an example that includes the LVDS setup.

In the LVDS bridge you will need to specify the LCD timing. As an example, this is for the 10" Hantronix display used on the TS-TPC-8950:

&ldb {
	status = "okay";

	lvds-channel@0 {
		fsl,data-mapping = "spwg";
		fsl,data-width = <18>;
		status = "okay";
		primary;
		crtc = "ipu1-di0";

		display-timings {
			native-mode = <&timing0>;
			timing0: hantronix-svga1 {
				clock-frequency = <40000000>;
				hactive = <800>;
				vactive = <600>;
				hback-porch = <46>;
				hfront-porch = <210>;
				vback-porch = <23>;
				vfront-porch = <12>;
				hsync-len = <20>;
				vsync-len = <10>;
				de-active = <1>;
				hsync-active = <1>;
				vsync-active = <1>;
				pixelclk-active = <0>;
			};
		};
	};
};

LEDs

The kernel provides access to control the LEDs using the sysfs:

# Set Red led on
echo 1 > /sys/class/leds/red-led/brightness
# Set Red led off
echo 0 > /sys/class/leds/red-led/brightness

# Set Green led on
echo 1 > /sys/class/leds/green-led/brightness
# Set Green led off
echo 0 > /sys/class/leds/green-led/brightness

The kernel provides various triggers that can be useful for debugging purposes. The trigger for a given LED is in its directory:

echo "heartbeat" > /sys/class/leds/red-led/trigger

Trigger value	LED toggles on
none	Default, no action
mmc0	MicroSD card activity
mmc1	eMMC activity
mmc2	WIFI SDIO activity
timer	2hz blink
oneshot	Blinks after delay. ^[1]
heartbeat	Similar to timer, but varies the period based on system load
backlight	Toggles on FB_BLANK
gpio	Toggle based on a specified gpio. ^[2]
cpu0	Blink on CPU core 0 activity
cpu1	Blink on CPU core 1 activity
cpu2	Blink on CPU core 2 activity
cpu3	Blink on CPU core 3 activity
default-on	Only turns on by default. Only useful for device tree.
transient	Specify on/off with time to turn off. ^[3]
flash/torch	Toggle on Camera activation. Not currently used.

↑ See the Kernel documentation for more details
↑ When this trigger is set, a "gpio" file appears in the same directory which can be used to specify what GPIO to follow when it blinks
↑ See the Kernel documentation for more details

MicroSD Card Interface

The i.MX6 SDHCI driver supports MicroSD (0-2GB), MicroSDHC (4-32GB), and MicroSDXC(64GB-2TB). The cards available on our website on average support up to 16MB/s read, and 22MB/s write using this interface. The linux driver provides access to this socket at /dev/mmcblk1 as a standard Linux block device.

This graph shows our SD write endurance test for 40x TS-7553 boards. These boards are running a doublestore stress test on 4GB Sandisk MicroSD cards. A failure is marked on the graph for a card once a single bit of corruption is found.

See chapter 67 of the i.MX6 reference manual for the specific CPU variant for more information on the mmc controller.

We have performed compatibility testing on the Sandisk MicroSD cards we provide. We do not suggest switching brands/models without your own qualification testing. While SD cards specifications are standardized, in practice cards behave very differently. We do not recommend ATP or Transcend MicroSD cards due to known compatibility issues.

Our testing has shown that on average microSD cards will last between 6-12TB. After this cards can begin to experience corruption, or stop being recognized by the host PC. This may be enough storage for many applications to write for years without problems. For more reliable storage consider using the eMMC. Our endurance testing showed a write lifetime on average of about 123 TiB.

MicroSD cards should not have power removed during a write or they will have disk corruption. Keep the filesystem mounted read only if this is a possibility. It is not always possible for fsck to recover from the types of failures that will be seen with SD power loss. Consider using the eMMC for storage instead which is far more resilient to power loss.

NVRAM

The RTC includes 120 bytes of NVRAM which can be used for custom applications. The utility 'nvramctl' can be used to read/write the NVRAM. The source for this utility is available from our ts4900-utils github.

The utility reads/writes a byte at a time, and returns the value in hex.

nvramctl --addr 10 --set 0x40
nvramctl --addr 10 --get
# Returns "nvram10=0x40".
# This can also be used with eval
eval $(nvramctl --addr 10 --get)
echo $nvram10
# Returns "0x40"

The NVRAM code can be included in your application by using these two files:

PCIe

The i.MX6 includes one PCIe 2.0 bus which is brought out to the baseboard on CN2. See the CPU reference manual for more information on the bus, or see the Linux Kernel menuconfig for more information on supported PCIe devices.

PWM

The PWM controller is accessed through the Linux driver. PWM is available on these pins:

CN1_19 (channel 1) (LCD Data 8)
CN1_21 (channel 2) (LCD Data 9)
CN2_74 (channel 2) (replaces USB_OTG_ID)
CN1_57 (channel 3)

This will require modifying the kernel or device tree to set up these pins as PWM. See the #Compile the Kernel section to get a build environment working. You will then need to modify either a baseboard specific device tree, or the fallback arch/arm/boot/dts/imx6qdl-ts4900.dtsi. This example will assume the latter.

In this case this is the example PWM channel 3 on the TS-4900 on CN1_57. First the pin must be configured to be PWM and not a GPIO. Add the pinctrl_pwm3 after the imx-ts4900 {:

iomuxc {
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_hog>;

	imx6-ts4900 {
		pinctrl_pwm3: pwm3grp {
			fsl,pins = <
				MX6QDL_PAD_SD4_DAT1__PWM3_OUT		0x1b088
			>;
		};

The MX6QDL_PAD_SD4_DAT1__PWM3_OUT pad name comes from imx6q-pinfunc.h (or imx6dl-pinfunc.h). The format follows MX6QDL_PAD_<CPU Pad Name>__<Function of that pad>. This specifies SD4_DAT1 to be used as PWM3's output.

At the end of the file enable the PWM controller, and point at this pinctrl:

&pwm3 {
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_pwm3>;
	status = "okay";
};

This will attach a driver to actually drive that pin that is now configured for PWM. After rebuilding and installing this device tree you will now have a directory "/sys/class/pwm/pwmchip0". This can be used to control the PWM.

# Each PWM controller has "1" pwm which will be pwm channel 0
echo 0 > /sys/class/pwm/pwmchip0/export

This will create a pwm0 directory under pwmchip0 which has these files:

period	Total period, inactive and active time in the PWM cycle specified in nanoseconds.
duty_cycle	Active time of the PWM signal specified in nanoseconds. Must be less than the period.
enable	Write 1 to enable, 0 to disable
polarity	When the pwm is disabled this can be written as "normal" for default behavior or "inversed" to invert the signal.

As an example, this will set a 50khz signal with 50 percent duty cycle.

# 20us is the period for 50khz
echo 20000 > /sys/class/pwm/pwmchip0/pwm0/period
echo 10000 > /sys/class/pwm/pwmchip0/pwm0/duty_cycle
echo 1 > /sys/class/pwm/pwmchip0/pwm0/enable

A common use of the PWM is for backlight control which is specified in the device tree. Our TS-TPC-8390 baseboard device tree can be used as an example.

In addition to setting up the PWM as demonstrated above, the PWM is connected to the pwm-backlight driver.

	backlight_lcd {
		compatible = "pwm-backlight";
		pwms = <&pwm3 0 5000000>;
		brightness-levels = <0 128 140 160 180 200 220 240 255>;
		default-brightness-level = <8>;
		power-supply = <&reg_3p3v>;
	};

This specifies PWM3 to run with 5000000 ns periods (200hz) with duty cycles specified in brightness-levels up to 255. This example creates 8 levels of brightness for the backlight, but more duty cycles can be added if more levels are needed.

RTC

We include the Intersil ISL12020 RTC onboard. This provides a long RTC battery life, as well as a built in temperature sensor to provide ±5 ppm across -40 to 85 C. The RTC appears at "/dev/rtc0" in our images, and is accessed using the standard hwclock command.

USB

USB OTG

Depending on which baseboard the TS-4900 is used with, the OTG port may be usable as host, or it may be brought out to a MicroAB port allowing it to be host or device. Several devices are compiled into the default kernel. Additional devices can be compiled into the kernel by following the section here.

USB Serial

modprobe g_serial use_acm=1

This will create a /dev/ttyGS0. See the kernel documentation for more information:

USB Ethernet

modprobe g_ether

This provides a usb0 network interface which simulates an ethernet network connection between the host pc and the i.MX6.

Windows driver inf

USB Host

The TS-4900 provides a standard USB 2.0 host supporting 480Mb/s. Typically this is interfaced with by using standard Linux drivers, but low level USB communication is possible using libusb.

Many of our off the shelf baseboards provide a GPIO to toggle power to USB devices. This can be used to save power, or to reset USB devices that get stuck in a bad state.

# Power disabled
echo 1 > /sys/class/leds/en-usb-5v/brightness
sleep 2 # let any devices reset
# Enable power
echo 0 > /sys/class/leds/en-usb-5v/brightness

Note:

The USB OTG which can act as a host does not always use the same controllable 5V supply. Refer to the schematic's EN_USB_5V/USB_5V for more information on this control.

SATA

The i.MX6 Quad and Dual include integrated SATA II support. This interface has been tested to provide 72 MiB/s write, and 75 MiB/s read through block access. In Linux this is accessed through the "/dev/sda" device node:

[    1.768036] ata1: SATA link up 3.0 Gbps (SStatus 123 SControl 300)
[    1.785377] ata1.00: ATA-8: MKNSSDAT30GB-DX, 507ABBF0, max UDMA/133
[    1.791716] ata1.00: 58626288 sectors, multi 16: LBA48 NCQ (depth 31/32)
[    1.805380] ata1.00: configured for UDMA/133
[    1.810320] scsi 0:0:0:0: Direct-Access     ATA      MKNSSDAT30GB-DX  507A PQ: 0 ANSI: 5
[    1.819459] sd 0:0:0:0: [sda] 58626288 512-byte logical blocks: (30.0 GB/27.9 GiB)
[    1.827427] sd 0:0:0:0: [sda] Write Protect is off
[    1.832812] sd 0:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[    1.843621]  sda: sda1
[    1.847381] sd 0:0:0:0: [sda] Attached SCSI dis

SPI

The CPU has 2 SPI controllers which are accessible through either specific kernel drivers, or userspace using the /dev/spi interface. To utilize SPI, most projects will end up with a customized device tree, so setting up the kernel build environment will be necessary. See the kernel compile guide here for more details.

Open the device tree source file such as arch/arm/boot/dts/imx6qdl-ts4900-reve.dtsi or arch/arm/boot/dts/imx6qdl-ts4900.dtsi, or find the device tree that matches your baseboard. The kernel requires a spidev device be added to the relevant ECSPI controller. For example:

&ecspi2 {
	fsl,spi-num-chipselects = <2>;
	cs-gpios = <&gpio6 2 0>, <&gpio5 29 0>;
	pinctrl-names = "default";
	pinctrl-0 = <&pinctrl_ecspi2>;
	status = "okay";

	serial1: max3100-1@0 {
		compatible = "max3100-ts";
		reg = <0>;
		interrupt-parent = <&gpio1>;
		interrupts = <4 IRQ_TYPE_LEVEL_LOW>;
		spi-max-frequency = <10000000>;
		loopback = <0>;
		crystal = <1>;
		poll-time = <100>;
	};

	spidev: spi@1 {
		compatible = "spidev";
		reg = <1>;
		spi-max-frequency = <18181818>;
	};
};

In this case ECSPI2 is configured with a spidev at 18.181818MHz which will be available at /dev/spidev1.1 (<bus counting from 0>.<chipselect>). This example adds the spidev device for the offboard chip select. The above example uses GPIO 5 29 which is SPI_2_CS#/CN2_65. The line "reg = <1>;" must be declared to select which chip select in the "cs-gpios" array will be asserted when communicating to your device. After this is configured rebuild the kernel and install your new device tree.

On this board ECSPI1 is used for the boot flash. If this bus is expanded care must be taken to limit trace lengths, and make sure the chip selects are not asserted out of boot. If another device attempts to drive MISO on startup, or the trace lengths are long enough to cause signal integrity issues these will prevent boot.

The SPI max speed is varied between CPU, pins, and if the SPI transaction is read/write:

Bus	CPU	Read	Write
ECSPI1	IMX6Q	40 ns (25.00 MHz)	15 ns (66.66 MHz)
ECSPI1	IMX6DL	43 ns (23.25 MHz)	15 ns (66.66 MHz)
ECSPI2	IMX6Q	55 ns (18.18 MHz)	15 ns (66.66 MHz)
ECSPI2	IMX6DL	43 ns (23.25 MHz)	15 ns (66.66 MHz)

See the i.MX6 datasheet for further details on SPI timing such as setup, hold, and propagation delays.

Once you have a /dev/spidev device, you can open this file and use the standard Linux SPI API. For more information see the documentation and sample code:

Onboard SPI Flash

This board includes 8MiB of SPI flash using a Micron N25Q064A13ESE40F. The CPU uses this for the initial boot to load u-boot, as well as the u-boot environment. In Linux this is accessed with the /dev/mtdblock devices.

Bytes	Size	Description
0-0x3ff	1KB	Unused
0x400-0xfffff	0.999MiB	U-boot
0x100000-0x101fff	8KiB	U-boot environment
0x102000-0x700000	5.992MiB	Unused

TWI

The i.MX6 supports standard I2C at 100khz, or using fast mode for 400khz operation. The CPU has 2 I2C buses used on the TS-4900.

I2C 1 is internal to the TS-4900 and connects to the RTC and FPGA.

Address	Device
0x28-0x2f	#FPGA
0x57	#NVRAM
0x6f	#RTC

The second I2C bus is brought out on CN2_28 (SCL) and CN2_30 (SDA). This bus has no devices except those added by the baseboard.

Note:

It is also possible to request the kernel to bitbang additional I2C buses as needed. See an example here.

The kernel makes the I2C available at /dev/i2c-#. You can use the i2c-tools (i2cdetect, i2cget, i2cset), or you can write your own client.

Watchdog

The CPU's watchdog timer is a hardware component that helps ensure the stability and responsiveness of the system. It does this by resetting the system if it detects that a certain process or application is not functioning as expected. If the watchdog timer is not regularly reset or "fed," it will expire and trigger a system reset.

By default, the watchdog timer has a timeout period of 60 seconds. However, it is powered by a ring oscillator that may not be perfectly accurate, meaning the timer may expire more quickly than expected. To ensure that the watchdog timer does not expire prematurely, it should be reset or "fed" at least 4 times more frequently than its configured timeout period. For example, if the timeout is set to 60 seconds, the watchdog should be reset at least every 15 seconds.

The kernel provides an interface to the watchdog driver at /dev/watchdog. This interface can be used to enable the watchdog timer by feeding it from an application. For more information on using the watchdog timer, refer to the kernel documentation at the following links:

WIFI

The TS-4900 releases prior to E included the LSR TIWI-BLE using the TI wl1271 chipset. When this went end of life the rev E boards were changed to support the Silex SX-SDMAC2832S+ module based on the QCA9377 chipset.

Silex WIFI (Rev E or later)

This board uses the Silex SX-SDMAC2832S+ based on the Qualcomm QCA9377 chipset.

Key Features:

FCC/IC/CE/MIC Modular Certification
Dual band, 2.4GHz and 5GHz
Station, AP, and Monitor mode
802.11 a/b/g/n/ac
Bluetooth 4.2 (BD/EDR/LE)
-40 to 85C operation

Linux uses the "wireless-tools", "wpa-supplicant", and "hostapd" packages to support most of the functionality in this module. Refer to the distribution support for #Yocto, #Debian, or #Android for more information.

The module can be put in monitor mode where it can capture packets. The driver must be loaded with connection mode 4 to support this:

modprobe -r wlan
modprobe wlan con_mode=4
ifconfig wlan0 up
iwpriv wlan0 setMonChan 36 2
tcpdump -i wlan0 -w test.pcap

This will generate a test.pcap that includes raw wireless frames.

On startup, the WIFI driver will print something like this in dmesg:

[   17.486980] wlan: loading driver v4.5.25.34
[   17.494255] hifDeviceInserted: Dumping clocks (50000000,198000000)
[   17.694671] ol_download_firmware: chip_id:0x5020001 board_id:0x0
[   17.703277] ar6k_wlan mmc0:0001:1: Direct firmware load for bdwlan30.b00 failed with error -2
[   17.711952] __ol_transfer_bin_file: Failed to get bdwlan30.b00:-2
[   17.723468] __ol_transfer_bin_file: Trying to load default bdwlan30.bin
[   17.733833] Board extended Data download address: 0x0
[   17.759032] __ol_transfer_bin_file: Loading setup file qsetup30.bin
[   17.766946] ar6k_wlan mmc0:0001:1: Direct firmware load for qsetup30.bin failed with error -2
[   17.775554] __ol_transfer_bin_file: Failed to get qsetup30.bin:-2
[   18.288434] R0: wlan: [347:E :SAP] dfs_init_radar_filters[217]: Unknown dfs domain 0 
[   18.303731] Target Ready! : transmit resources : 3 size:1792, MaxMsgsPerHTCBundle = 32
[   18.315633] Payload Length Error : header reports payload of: 28 (256) endpoint buffer size: 64 
[   18.344251] ar6k_wlan mmc0:0001:1: Direct firmware load for wlan/wlan_mac.bin failed with error -2
[   18.356820] target uses HTT version 3.50; host uses 3.28
[   18.362148] DEBUGFS PEER MAC = 0x86:0x25:0x3f:0xe4:0xdf:0x46
[   18.362149] *** Warning: host/target HTT versions are different, though compatible!
[   18.377192] Host SW:4.5.25.34, FW:0.0.1.1047, HW:QCA93x7_REV1_1
[   18.383696] ENTER sme_set_btc_coex_dutycycle = 30
[   18.388932] ENTER sme_set_btc_coex_dutycycle =30
[   18.394806] ath_hif_sdio: HIF (Atheros/multi-bss)
[   18.399589] wlan: driver loaded in 912000

The missing files are optional firmware files that are not used in this use case.

TI WIFI (Rev D or earlier)

This board includes a TiWi-BLE SDIO module that uses the Texas Instruments WL1271L Transceiver. Linux provides support for this using the wl12xx driver. See the LSR site for detailed product information.

Summary Features:

IEEE 802.11 b/g/n
2.4GHz
Linux drivers include support for client and AP mode
Host up to 8 clients on AP
Industrial temp, -40 to 85C
Certifications
- FCC Bluetooth® Grant
- FCC WLAN Grant
- IC
- CE
- SAR Testing
- SAR Testing EU

Linux uses the "wireless-tools", "wpa-supplicant", and "hostapd" packages to support most of the functionality in this module. Refer to the distribution support for #Yocto, #Debian, or #Android for more information.

External Interfaces

TS-SOCKET

The TS-SOCKET System-on-Moduless (SoMs) all use two high density 100 pin connectors for power and all I/O. These follow a common pinout for various external interfaces so new modules can be dropped in to lower power consumption or use a more powerful processor. The male connector is on the baseboard, and the female connector is on the SoM. You can find the datasheet for the baseboard's male connector here. This can be ordered from the TS-SOCKET SoM product page as CN-TSSOCKET-M-10 for a 10 pack, or CN-TSSOCKET-M-100 for 100 pieces, or from the vendor of your choice, the part is an FCI "61083-102402LF".

In our schematics and our table layout below, we refer to pin 1 from the male connector on the baseboard. This does not match the manufacturers pin 1.

For designing a custom carrier board for the TS-4900 we recommend using the TS-8550 as a base: https://www.embeddedTS.com/documentation/ts-8550-schematic.pdf

CN1

CN2

Name	Pin		Pin	Name
NC	1		2	EXT_RESET# ^[1]
NC	3	C	4	EN_USB_5V ^[2]
NC	5	N	6	SD2_D2 ^[3]
NC	7	1	8	SD2_D3 ^[3]
OFF_BD_RESET# ^[4]	9		10	SD2_CMD ^[3]
NC	11		12	3.3V
NC	13	C	14	SD2_CLK ^[3]
5V ^[5]	15	N	16	5V ^[5]
NC	17	1	18	SD2_D0 ^[3]
LCD_D08	19		20	SD2_D1 ^[3]
LCD_D09	21		22	NC
LCD_D10	23	C	24	LCD_D00
LCD_D11	25	N	26	LCD_D01
LCD_D12	27	1	28	LCD_D02
5V ^[5]	29		30	LCD_D03
LCD_D13	31		32	LCD_D04
LCD_D14	33	C	34	LCD_D05
LCD_D15	35	N	36	V_BAT
LCD_D16	37	1	38	LCD_D06
LCD_D17	39		40	LCD_D07
LCD_D18	41		42	LCD_D21
LCD_D19	43	C	44	LCD_D22
LCD_D20	45	N	46	LCD_D23
5V ^[5]	47	1	48	EN_LCD_3.3V
LCD_CLK	49		50	NC
LCD_HSYNC	51		52	BOOT_MODE_0
LCD_VSYNC	53	C	54	BOOT_MODE_1
LCD_DE	55	N	56	SPI_1_MISO
LCD_PWM	57	1	58	SPI_1_MOSI
SPI_FLASH_CS# ^[6]	59		60	SPI_1_CLK
SPI_1_CS1#	61		62	Ground
CN1-63 / ttymxc3 TXEN	63	C	64	EIM_DA15 / MUX_AD_15
EIM_EB1	65	N	66	EIM_DA14 / MUX_AD_14
CN1-67 / ttymxc1 TXEN	67	1	68	EIM_DA13 / MUX_AD_13
CAN2_RXD	69		70	EIM_DA12 / MUX_AD_12
CAN2_TXD	71		72	EIM_DA11 / MUX_AD_11
PUSH_SW#	73	C	74	EIM_DA10 / MUX_AD_10
Ground	75	N	76	EIM_DA09 / MUX_AD_09
EIM_A21	77	1	78	EIM_DA08 / MUX_AD_08
EIM_BCLK	79		80	EIM_DA07 / MUX_AD_07
EIM_A18	81		82	EIM_DA06 / MUX_AD_06
EIM_OE	83	C	84	EIM_DA05 / MUX_AD_05
EIM_A20	85	N	86	EIM_DA04 / MUX_AD_04
CN1-87 / #Offboard Clock	87	1	88	EIM_DA03 / MUX_AD_03
EIM_A22 / Offboard IRQ 69	89		90	EIM_DA02 / MUX_AD_02
EIM_A23	91		92	EIM_DA03 / MUX_AD_01
EIM_A24	93	C	94	EIM_DA00 / MUX_AD_00
Ground	95	N	96	EIM_LBA / BUS_ALE#
EIM_WAIT / BUS_WAIT#	97	1	98	EIM_RW / SDBOOT / BUS_DIR
EIM_EB1 / BUS_BHE#	99		100	EIM_CS0 /BUS_CS#

Name	Pin		Pin	Name
MDI_0_P	1		2	ETH_ACT_LED
MDI_0_M	3	C	4	ETH_LINK_LED
ETH_CT	5	N	6	RED_LED#
MDI_1_P	7	2	8	GREEN_LED#
MDI_1_M	9		10	LVDS_TX3_P
ETH_CT	11		12	LVDS_TX3_M
3.3V ^[7]	13	C	14	Ground
Ground	15	N	16	LVDS_TX2_P
MDI_2_P	17	2	18	LVDS_TX2_M
MDI_2_M	19		20	NC
Ground	21		22	LVDS_TX0_P
MDI_3_P	23	C	24	LVDS_TX0_M
MDI_3_M	25	N	26	Ground
1.2V	27	2	28	I2C_2_CLK
HOST_USB_M	29		30	I2C_2_DAT
HOST_USB_P	31		32	NC
1.2V	33	C	34	NC
USB_OTG_M	35	N	36	AUD_CLK
USB_OTG_P	37	2	38	AUD_FRM
3.3V ^[7]	39		40	AUD_TXD
LVDS_CLK_M	41		42	AUD_RXD
LVDS_CLK_P	43	C	44	Ground
Ground	45	N	46	LVDS_TX1_M
PCIE_TX_P	47	2	48	LVDS_TX1_P
PCIE_TX_M	49		50	Ground
Ground	51		52	CSI0_DAT12
PCIE_RX_M	53	C	54	AUD_MCLK
PCIE_RX_P	55	N	56	CSI0_DAT17
DDR_1.5V ^[8]	57	2	58	SD4_DAT7
PCIE_CLK_P	59		60	SD3_RST
PCIE_CLK_M	61		62	GPIO_16
1.8V ^[9]	63	C	64	GPIO_17
SPI_2_CS#	65	N	66	CSI0_DAT13
SPI_2_MOSI	67	2	68	GPIO_19
SPI_2_MISO	69		70	CSI0_MCLK
SPI_2_CLK	71		72	CSI0_PIXCLK
Ground	73	C	74	USB_OTG_ID
SATA_RX_M	75	N	76	USB_OTG_VBUS
SATA_RX_P	77	2	78	CN2-78 / COM1 txd
3.3V	79		80	CN2-80 / COM1 rxd
SATA_TX_M	81		82	CN2-82 / COM2 txd
SATA_TX_P	83	C	84	CN2-84 / COM2 rxd
Ground	85	N	86	CN2-86 / COM3 txd
NC	87	2	88	CN2-88 / COM3 rxd
NC	89		90	CN2-90 / COM4 txd
NC	91		92	CN2-92 / COM4 rxd
DEBUG_TXD	93	C	94	CN2-94
DEBUG_RXD	95	N	96	CN2-96
CAN_1_TXD	97	2	98	CN2-98
CAN_1_RXD	99		100	CN2-100

↑ EXT_RESET# is an open-drain input used to reboot the CPU.
↑ This is an output which can be manipulated in the #Syscon. This pin can optionally be connected to control a FET to a separate 5V rail for USB to allow software to reset USB devices.
↑ ^3.0 ^3.1 ^3.2 ^3.3 ^3.4 ^3.5 This SD interface is the same one used by the MicroSD on the TS-4900. Only one can be used at a time.
↑ OFF_BD_RESET# is an output from the System-on-Module (SoM) that automatically sends a reset signal when the unit powers up or reboots. It can be connected to any IC on the base board that requires a reset.
↑ ^5.0 ^5.1 ^5.2 ^5.3 The 5V power pins should each be connected to a 5V source.
↑ This is used during production to boot to an offboard SPI flash. This pin should typically be left unconnected.
↑ ^7.0 ^7.1 The TS-4900 regulates a 3.3V rail which can source up to 700mA. Designs should target a 300mA max if they intend to use other SoMs.
↑ This pin is used as a test point to verify the RAM has a correct voltage for debugging
↑ This pin is used as a test point for debugging

Specifications

Power Specifications

The TS-4900 only accepts 5V input to the board.

Input	Min voltage	Max voltage
5V input	4.75	5.25

Power Consumption

The TS-4900's power consumption can vary a lot depending on the build and activity of the board. Most of the power savings happens automatically when the CPU and GPU are idle, but it is also possible to disable the Ethernet PHY for additional savings. No savings were observed putting eMMC or the ICE40 in reset.

# Put ETH PHY in reset
echo "116" > /sys/class/gpio/export
echo "high" > /sys/class/gpio/gpio116/direction

These tests are performed on a TS-8550 with most active components removed to measure power of just the TS-4900 itself. Ethernet is not connected unless otherwise specified, and serial is disconnected during the measurement. Not all combinations are included in these tests but the TS-4900-1024-S10S-C is the lowest power consumption board, and the TS-4900-2048-4096F-Q10S-RTC-WIFI-E consumes the most power.

TS-4900-1024-S10S-C
Test	Average (W)	Max (W)
Idle with Ethernet PHY in reset	0.59	1.48
Idle (no changes)	0.99	1.88
Idle (ethernet connected)	1.25	2.37
Busy CPU (openssl speed)	1.94	3.35

TS-4900-2048-4096F-Q10S-RTC-WIFI-E
Test	Average (W)	Max (W)
Idle with Ethernet PHY in reset	1.28	2.31
Idle (no changes)	1.66	2.70
Idle (ethernet connected)	1.99	3.59
WIFI active (iperf over wpa2)	2.50	4.48
Busy CPU (5x openssl speed)	4.76	6.33
Busy CPU+GPU	4.90	10.35

Temperature Specifications

The i.MX6 CPUs we provide off the shelf are either a solo industrial, solo commercial, or quad core extended temperature. The TS-4900 is designed using industrial components that will support -40C to 85C operation, but the CPU is rated to a max junction temperature rather than an ambient temperature. We expect the solo to work to 80C ambient while idle with a heatsink and open air circulation. To reach higher temperatures with this or other variants of this CPU some custom passive or active cooling may be required.

Model Number	Operating Minn	Cooling Temp ^[1]	Passive Temp ^[2]	Critical/Max Junction Temp ^[3]
TS-4900-S8S	-40C	75C	85C	105C
TS-4900-S10S	0C	75C	85C	105C
TS-4900-Q10S	-20C	75C	85C	100C

↑ CPU stops all throttling below this temperature
↑ CPU begins throttling until the cooling temperature
↑ CPU Max temperature. Linux will shut down to cool in u-boot at this temperature.

For custom builds with different CPUs these are also exposed in /sys/:

# Passive
cat /sys/devices/virtual/thermal/thermal_zone0/trip_point_0_temp
# Critical
cat /sys/devices/virtual/thermal/thermal_zone0/trip_point_1_temp

The current CPU die temp can be read with:

cat /sys/devices/virtual/thermal/thermal_zone0/temp

When the CPU heats up past the cooling temp on a first boot, it will take no action. Once it hits the passive temperature however the kernel will reduce clocks in an attempt to passively cool the CPU. This will show a kernel message:

[  158.454693] System is too hot. GPU3D will work at 1/64 clock.

If it cools back down below the cooling temperature it will spin back up the clocks.

[  394.082161] Hot alarm is canceled. GPU3D clock will return to 64/64

If it continues heating to the critical temperature it will overheat and reboot. When the system boots back up u-boot will block the boot until the temperature has been reduced to the Cooling Temp+5C. This will be shown on boot with:

U-Boot 2015.04-07857-g486fa69 (Jun 03 2016 - 12:04:30)

CPU:   Freescale i.MX6SOLO rev1.1 at 792 MHz
CPU Temperature is 105 C, too hot to boot, waiting...
CPU Temperature is 102 C, too hot to boot, waiting...
CPU Temperature is 99 C, too hot to boot, waiting...
CPU Temperature is 90 C, too hot to boot, waiting...
CPU Temperature is 86 C, too hot to boot, waiting...
CPU Temperature is 84 C, too hot to boot, waiting...
CPU Temperature is 80 C, too hot to boot, waiting...
CPU Temperature is 80 C, too hot to boot, waiting...
CPU Temperature is 80 C, too hot to boot, waiting...
CPU:   Temperature 78 C
Reset cause: WDOG
Board: TS-4900

Note:

Pre-2015 U-boots will not block for temperature.

These temp tests show how the TS-4900 functions with/without the heatsink. Note that the listed adhesive heatsink is not recommended with the i.MX6, but the data is provided as a reference for a smaller heatsink.

IO Specifications

The GPIO external to the unit are all nominally 3.3 V, but will vary depending on if they are CPU/FPGA pins.

The CPU pins can be adjusted in software and will have initial values in the device tree. This allows for adjustment of the drive strength and pull strength of the I/O pins. See the device tree for your kernel for further details on a specific I/O.

The FPGA I/O cannot be adjusted further in software.

IO	Typical Range	Absolute Range	Logic Low	Logic high	Drive strength
External CPU GPIO	0 V to 3.3 VDC	-0.5 V to 3.6 V	0.99 V	2.31 V	27.5 mA
External FPGA GPIO	0 V to 3.3 VDC	-0.5 V to 3.75 V	0.8 V	2.0 V	12 mA

Refer to the iCE40 Family Datasheet for more detail on the FPGA I/O. Refer to the CPU quad or solo datasheet for further details on the CPU I/O.

Note:

Do not drive any I/O from an external supply until 3.3 V Rail is is valid. Doing so can violate the power sequencing causing boot failures or damage to the device.

Rail Specifications

The TS-4900 generates all rails from the the 5V input. This table does not document every rail. This will only cover those that can provide power to an external header for use in an application.

5V will allow you to bypass our regulator allowing more current, but the absolute max supply can provide 5A to the board.

Rail	Current Available	Location
AN_1.8V	10mA	CN2_63
3.3V	700mA	CN2_39, CN2_79

Revisions and Changes

TS-4900 PCB Revisions

Revision	Changes
A	Initial Release
B	Not released
C	Parts moved away from mounting holes U4-K23(EIM_EB1) and U4 H21(DIO_10) swapped for offboard EIM Bus. 5 LVDS pairs added to CN2 in reserved pins CPU JTAG removed from CN2 for LVDS pairs Available on testpoints Audio MCLK changed to CN2-54 Add PU resistor on PHY reset FET clamp for 3.3V FET switch for RTC power Added bias resister for PCIe clock CN2 DIO same as REV A except: CN2_56 is CSI0_DAT17, REV A was GPIO_5 CN2_58 is SD4_DAT7, REV A was GPIO_6 CN2_60 is SD3_RST, REV A was GPIO_9 CPU pin A20 (SD4_DAT3) is strapped low to indicate new revision. CTS/RTS both connected to FPGA so a uart with full control signals can be routed to bluetooth.
D	Moved components to create a clearance of 4.2mm around the CPU for the heatsink Changed eMMC to 153 ball version to fit larger eMMC disks Added EIM Byte Enable signal to CN1 pin 22 based on build option. FPGA ball P4 is now used to enable SD card 3.3V power. Allow FPGA_SPI_CS# to be biased with new resistor for OTP modes FPGA_SPI_CS# is now brought out to CN2_34 which was previously a no connect. i.MX6 ball L6 is connected to ground to detect the new revision. U-boot includes the PCB revision as a variable.
E	LSR TIWI-BLE Replaced with Silex SX-SDMAC2832S+

Product Change Notices

These bill of material (BOM) changes are those that have been made which may affect user software. While we try to pick parts that will have a long lifetime and remain unchanged for as long as possible. Most changes or part qualifications have little to no user impact. If any changes do possibly impact customers or require software updates, then we will document them in the following sections.

Sign up for PCS updates to receive notifications of when an upcoming change is required.

WIFI Module replacement

Due to an EOL the Wi-Fi module this part is being replaced with the Silex SX-SDMAC2832S+ starting with PCB revision E.

For users who do not use Wi-Fi and write their own image, no action is required to support REV E boards.

For users with custom u-boots this requires a u-boot change to support loading the new PCB revision device trees:

U-boot patch

U-boot will now search for the device tree preferring a file with the -rev<pcbrev> in the file name. For example, on a quad core TS-4900 REV E on a TS-TPC-8390 which is baseboard id 2, it will attempt to load these files in this order:

imx6q-ts4900-reve-2.dtb
imx6q-ts4900-reve.dtb
imx6q-ts4900-2.dtb
imx6q-ts4900.dtb

Boards before REV E will not attempt to load the reve dtb files.

When using the older images which did not have the pcb rev in the device tree, this will fall back to the older file but the startup output will show this output while it checks for the updated device tree.

Booting from the eMMC ...
** File not found /boot/boot.ub **
** File not found /boot/imx6q-ts4900-reve-2.dtb **
** File not found /boot/imx6q-ts4900-reve.dtb **
42451 bytes read in 126 ms (328.1 KiB/s)

For users with unmodified kernels these can be updated to include the new Wi-Fi support with a tar:

This can be installed directly to the board:

wget https://files.embeddedTS.com/ts-socket-macrocontrollers/ts-4900-linux/kernel/linux-4.9.11-20200701.tar.bz2
tar -xf linux-4.9.11-20200701.tar.bz2 -C /

This can also be used to install over an existing image:

mkdir /tmp/image/
sudo tar --numeric-owner -xf old-image.tar.bz2 -C /tmp/image/
sudo tar -xf linux-4.9.11-20200701.tar.bz2 -C /tmp/image/
sudo tar --numeric-owner -cjf new-image.tar.bz2 -C /tmp/image .

Users with custom device trees or kernels to support custom carrier boards will need to sync up to our latest sources. The new Wi-Fi module uses the qcacld-2.0 driver which is external to the kernel tree. See the Compile the kernel section for an example of building this external wlan.ko module.

For users with custom kernels these should be updated to our latest commits:

4.9 3544502eff51a659101411ed7879c0596e7c73f5
4.1 04b83989d3930580a2f6ee70ac4483e6728e1fcf

Existing images will also need to be updated to support the firmware required by these new chipsets. If either of the above stock kernels are installed these packages also include the required firmware.

The required firmware is present in our updated images, the above tar including the kernel, or the the silex-firmware recipe in yocto shows the required files and where to install them:

SPI Flash Vendor Change

Due to an EOL the SPI flash on this product is changing. The old part is a Micron N25Q064A13ESE40F. Two new parts were qualified to reduce the impact of any potential EOL in the future. The new parts are the Microchip's SST26VF064BA, and ISSI's IS25LP064A.

Most applications will not be affected by this change unless they are manually accessing /dev/mtdblock0 or creating a custom U-Boot. In those cases some updates will be required.

Linux Kernel Changes

Rebuilding the latest kernel in our git will include these changes, but the specific commits for our various kernel branches are:

U-Boot Changes

These three patches are required for the new flash:

part1, part2, part3

Images with support

Any of our Linux images after March 7th, 2018 include support for this new SPI flash.

New eMMC chip

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

This may require a change to production processes for those who were manually set write reliability and enhanced area for the previous chip. The enh_area and write_reliability settings are permanent and these partition settings are locked once any of them are set. This led to scripts verifying write reliability was set and assuming both were set. The eMMC section includes an example shell script for enabling atomic writes on both versions of this chip.

New eMMC chip (2023-02)

This product will be built with the Alliance ASFC4G31M-51BIN. This is an equivalent 4 GB part and it is expected to have generally no impact to software. There are 2 notable differences:

1. The eMMC boot partitions (/dev/mmcblk*boot0/boot1) are 4 MB instead of 16 MB. These are not used on this series as they are not used by any default software, and are read only by default.

2. For users previously using Micron's proprietary tools to view the remaining life of the eMMC, the newer chipsets should instead use the data provided by "mmc extcsd read" as remaining lifetime is now part of the newer eMMC standards.

Like the previous Micron part update this eMMC by default comes with write reliability already enabled. Our endurance testing shows this part lasting as long as the previous Micron part as well, so we do not expect any other notable impacts to users.

TS-4900 Errata

Errata	Description	Fix/workaround.
PHY violates IEEE specification for jitter	The TS-4900 PHY's published errata here includes items added on 07-26-16 for "1000BASE-T Transmitter Jitter fails to meet IEEE compliance specification" and "1000BASE-T Transmitter Distortion fails to meet IEEE compliance specification". Both errata can cause linking issues, and the Jitter related errata can cause packet loss with some link partners at 1000Base-T.	Change out the link partner on the other end of the network cable. If the PHY in the linked device meets or exceeds the IEEE specs it will compensate for the errata of the PHY on the TS-4900. Alternatively reducing the ethernet speed to 100BASE-T should resolve the issue.

U-Boot Changelog

U-boot release date	Changes
Jul-22-2014	Initial Release
Sep-24-2014	Instead of pressing any key during startup, now it requires Ctrl+C. This is to prevent any serial noise from stopping the board in u-boot. The board will now attempt to load /boot/boot.ub before continuing. This is intended for booting environments like QNX, android, and more that cannot use the standard boot arguments.
Nov-06-2014	Updated ddr calibration for new build (TS-4900 solo 800MHz industrial temp 1GB RAM) Enabled usb 5V by default for usb boot mechanism
Nov-19-2014	Updated to U-boot 2014.10 (from 2013.10) Functionally the same Included android boot image support Included fastboot support SATA boot fixes
Dec-01-2014	Added bbdetect command to 2014.10
Dec-05-2014	Ignored RPCERRORs from the UMNTALL RPC call after an NFS transaction. Not all nfs servers implement this and it should not invalidate the file transfer since it is just for state tracking on the server.
Jan-26-2014	Fixed USB 5V reset timing for boards with hubs. USB 5V is now disabled 500ms after OFF_BD_RESET is disabled. On older revs USB may not detect some peripherals if the USB 5V comes up before the hub is out of reset. Added "rcause" variable. This lets u-boot scripts make use of the reset cause in scripts. For example, if rcause is "POR" in the field, it may have experienced a brownout and an alternate kernel/os could be booted instead. If rcause is "WDOG" then either a reset or watchdog condition caused the reset. New "model" variable with "4900" or "7970", etc. This is so common usb blasters can be used and determine the model. new "rev" variable including "A" or "C". This is also now printed at startup.
Jan-29-2014	Included updates for REV C boards If I2C locks up, reset RTC FET for rare lockup. U-boot networking speed limited to 100Mb/s by default. Gigabit requires about 5 seconds to autonegotiate. 10/100Mb/s requires ~500ms. The common case being NFS booting which requires a 3-4MB kernel, 300kb of device tree, 100kb of fpga binary, gigabit only slows down booting. This does not disable gigabit for Linux.
Mar-12-2014	Fixed typo in RTC FET workaround Added EXT4 and FAT write support for Ubuntu Snappy Core
Jul-27-2015	Added fix for PCIe hang in Linux. Some of the GPR1 regs were not being reset after a reboot. U-boot will now reset these before going into Linux. This hang was not present on all CPUs, usually solo, and only if PCIe is enabled in the kernel.
Oct-07-2015	Corrected ice40 SPI MODE used during programming
Oct-14-2015	Added eth1addr mac address variable Added smsc95xx.macaddr=${eth1addr} to the default cmdline To use the new MAC address for the USB Ethernet on some carrier boards you need the latest kernel as of today to include this patch. Added sataboot command in default environment. Must be called manually or put in bootcmd to be used.
Dec-14-2015	Offboard SPI chip select is no longer asserted during FPGA programming.
Dec-21-2015	Increased drive strength for the Ethernet signals Removed smsx95xx parameter and switched to u-boot's device tree fixup to set mac for the second ethernet. This requires this u-boot and at least this kernel revision.
Mar-08-2016	Added REV D detection (not required for REV D support, just reporting). Improved I2C lockup recovery on startup.
Apr-05-2016	Added bmode command
May-18-2016	Improved FPGA programming reliability on new chips Shortened NFS timeout Made the nfs command not care about nfs mount/umount errors. This is optional in NFS and should not matter in u-boot. On our test servers (solaris and linux) this makes NFS much faster since we don't wait for a timeout after every single nfs command blocking on a nonexistent mount reply.
Oct-19-2016	Added simple POST test. This is not enabled by default so there is no behavior change unless the "post" command is called.
Apr-27-2017	Fixed USB OTG port's host mode
Mar-26-2017	Add support for SST26VF064BA, and IS25LP064A spi flashes
Mar-31-2020	Added support for the REV E hardware revision
Feb-10-2021	Improved fallback device trees for older TS-4900 hardware revisions

FPGA Changelog

The FPGA is stored in /boot/ts4900-fpga.bin on most images. The latest software releases will include the latest FPGA, but older images can be updated if the md5sum matches an outdated bitstream.

Release	md5sum	Changes
ts4900-fpga-20140924.bin	d400e6c7806998e0f1b6cceb0fec022b	Initial Release
ts4900-fpga-20150326.bin	630a108d8c1af527101ee6559949b761	Register map changed significantly GPIO are the same specific registers for redirecting certain pins have been removed in favor of the crossbar Added crossbar so most FPGA pins can be mapped to almost any other FPGA pin. implemented MAX3100 SPI uart in the FPGA to add one more uart. Updated mapping for REV C boards.
ts4900-fpga-20150603.bin	75d5ef9653662dca96e2813de2804387	Includes 3 MAX3100 based UARTs Fixed ttymxc3 RXD crossbar value Work around this with older bitstreams by running "tshwctl --addr 3 --poke 0x50"
ts4900-fpga-20150930.bin	bf93c03ef914cf008287c8cd60781cc8	Corrected CTS/RTS polarity in the MAX3100 UART Corrected flipped CTS/RTS on the CPU uart for bluetooth
ts4900-fpga-20170510.bin	86c7c3d7fb9c607af1ef55e1222b4416	Fixed TXEN on CPU UARTs not correctly asserting in some multi-byte transmits

Software Images

Yocto Changelog

Quad/Dual Image	Solo/Duallite Image	Changes
ts-x11-image-ts4900-quad-20140905235640.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20140908160116.rootfs.tar.bz2	Initial Release
ts-x11-image-ts4900-quad-20141119190447.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20141119204157.rootfs.tar.bz2	Systemd default Added /usr/lib/openssh/sftp-server (Fixes QtCreator/Eclipse deploy) Added QtQuick Added Sqlite to QT Added early TS-7970 support. Updated kernel with significant fixes, see github for more information.
ts-x11-image-ts4900-quad-20141224171440.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20141224175107.rootfs.tar.bz2	Updated Kernel Fixed ISL RTC errors hardware builds that omit the RTC Fixed I2C bus for 8390 ADC Added small pop fix for sgtl5000 on the 8390 Updated ts4900-utils New util 8390adc for reading the low speed MCP ADC Fixed tshwctl to support auto TX-EN RS485 on ttymxc1
ts-x11-image-ts4900-quad-20150331224909.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20150401003538.rootfs.tar.bz2	Updated to 3.10.53 kernel Significant fixes to GPU, UARTs, CAN and more. Added TS-TPC-8950 support Fixed 7" twinkling pixels on TS-8390 w/solo Included splash screen Updated to Yocto Dizzy for new freescale GPU support Added Chromium to default image (google-chrome) Updated toolchain to match dizzy image Included gstreamer in the image Updated FPGA with crossbar, max3100 based spi uart, bluetooth fixes (REV C only)
ts-x11-image-ts4900-quad-20150527173205.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20150528210615.rootfs.tar.bz2	Fixed networkd Enabled PCIe in default kernel Added I210 support for TS-7970
ts-x11-image-ts4900-quad-20150620060219.rootfs.tar.bz2	ts-x11-image-ts4900-solo-20150622150127.rootfs.tar.bz2	Added TS-7970 support
ts-x11-image-tsimx6-20150821190815.rootfs.tar.bz2		Updated to Yocto Fido Removed GTK3 packages to reduce image size (GTK2 still available) Removed distcc from default environment Includes QT 5.4.3 Included qtmultimedia, xcursor-transparent theme Updated Kernel Includes fix for rare screen flip issues
ts-x11-image-tsimx6-20150821190815.rootfs.tar.bz2		Included significantly fixed support for the TS-7970 I210 support is fixed, but some prototype boards will need to be RMA'd to get MACs assigned. All UARTs are now working Included tsmicroctl for reading the silabs ADC (p10-12 4-20mA included) Included load_fpga for software reloading fpgas later after boot Updated TS-4900 FPGA to have CTS/RTS fixed for bluetooth, and corrected CTS/RTS polarity on the max3100s
ts-x11-image-tsimx6-20151014183028.rootfs.tar.bz2		Corrected defconfig used in kernel Fixed WIFI and other modules If used with the u-boot release from 10-14-2015 this fixes the mac address for the smsc95xx
ts-x11-image-tsimx6-20151221232637.rootfs.tar.bz2		Fixed MAC address to use device tree as well as parameter for the latest u-boot support. Fixed tsgpio driver which was causing some incorrect DIO sets. The WIFI driver uses tsgpio for toggling the enable which also corrects the behavior of ifdown/ifup wlan0. Added rsync and lighttpd-cgi support
ts-x11-image-tsimx6-20160512161729.rootfs.tar.bz2		Added 100kohm pullups to the onboard/offboard SPI chip selects.
ts-x11-image-tsimx6-20161116215413.rootfs.tar.bz2		Updated to Yocto Jethro Updates to QT 5.5 Updated to 4.1.15 based on Freescale/NXP's imx_4.1.15_1.0.0_ga. Added improved support for TS-TPC-7990 New tshwctl with crossbar support.
ts-x11-image-tsimx6-20170301225516.rootfs.tar.bz2		Updated to Yocto Morty 2.2.1 with the same imx_4.1.15_1.0.0_ga kernel Includes QT 5.7.1 Included additional alsa utilities
ts-x11-image-tsimx6-20170731205110.rootfs.tar.bz2		Updated to Morty 2.2.2 Included QT Quick 1.x/2.x support Added support for TS-TPC-7990 REV C in kernel and ts4900-utils Updated kernel Fixed issue with ttyMAX* UARTs losing data or requiring the user to transmit before it continues to receive again Fixed issue with ttyMAX* loopbacks dropping the first character Added wilc3000 support for TS-TPC-7990 REV C WIFI
ts-x11-image-tsimx6-20180502184622.rootfs.tar.bz2		Updated to Yocto Morty 2.2.3 Add support for SST26VF064BA, and IS25LP064A spi flashes Fixed TS-TPC-7990 REV C WIFI
ts-x11-image-tsimx6-20180608232731.rootfs.tar.bz2		Added support for accelerated gstreamer playback
ts-x11-image-tsimx6-20200409220332.rootfs.tar.bz2		Updated to Yocto Zeus Added support for Silex WIFI driver
ts-x11-image-tsimx6-20211130163916.rootfs.tar.bz2		Added WIFI fix for solo TS-4900 on fallback device tree Fixed TS-7970 FPGA GPIOs > 32.
ts-x11-image-tsimx6-20211206183743.rootfs.tar.bz2		Added support for Silex Bluetooth

Debian Changelog

Image date	Debian Release	Image	Changes
20140929	Debian 7 Wheezy	debian-armhf-wheezy-20140929.tar.bz2	Initial Release
20141125	Debian 7 Wheezy	debian-armhf-wheezy-20141125.tar.bz2	Updated kernel with significant fixes, see github for more information. Included first TS-7970 FPGA
20160825	Debian 8 Jessie	debian-armhf-jessie-20160825.tar.bz2	New kernel - 3.10.53 (from freescale's 3.10.53_1.1.0_ga) instead of 3.10.17. Fixed CAN dropped frames (just under 1% of frames were dropped on 3.10.17) Fixed reported UART RX fifo overflows GPU fixes Kernel includes compiled in splash screen for quick graphical response on boot TS-TPC-8950 support added New FPGA (crossbar added, bluetooth fixed, and max3100 implemented) Added bluez, wireless-tools, usbutils, nfs-common, and pciutils into the image. Added Openssh server (generates on first boot)
20150526	Debian 8 Jessie	debian-armhf-jessie-20150526.tar.bz2	First update to Debian Jessie
20151008	Debian 8 Jessie	debian-armhf-jessie-20151008.tar.bz2	Included kernel support for TS-7970 REV A Updated to latest TS-4900 FPGA (20150603) Included openssh, generates keys on first boot. Remove /etc/ssh/key to regenerate. Included latest ts4900-utils with TS-7970 support.
20160512	Debian 8 Jessie	debian-armhf-jessie-20160512.tar.bz2	Fixed TS-7970 ttyMAX uarts (requires FPGA update) Fixed resolv.conf symlink to use resolvd Updated to 3.14.52 kernel Corrected TS-TPC-8950 calibration
20160512	Debian 8 Jessie	debian-armhf-jessie-20160512.tar.bz2	Moved to 4.1.15 kernel Updated Debian to latest Jessie changes Added latest ts4900-utils with improved TS-TPC-7990 support.
20170123	Debian 8 Jessie	debian-armhf-jessie-20170123.tar.bz2	Added support for TS-7970 REV D hardware Added support for TS-7990 REV B hardware
20170306	Debian 8 Jessie	debian-armhf-jessie-20170306.tar.bz2	Fixed resolv.conf symlink Added nfs-common Cleaned up old temporary files
20170327	Debian 8 Jessie	debian-armhf-jessie-20170327.tar.bz2	Fixed regression in TS-TPC-8950 support Adds root.version to list image date
20170419	Debian 8 Jessie	debian-armhf-jessie-20170419.tar.bz2	Fixed issue of missing U-boot splash screen disabling the backlight on REV B boards. Fixed potential issue with WIFI not being recognized. Added support for #TS-DC799-SILO board.
20170731	Debian 8 Jessie	debian-armhf-jessie-20170731.tar.bz2	Added support for TS-TPC-7990 REV C in kernel and ts4900-utils Updated kernel Fixed issue with ttyMAX* UARTs losing data or requiring the user to transmit before it continues to receive again Fixed issue with ttyMAX* loopbacks dropping the first character Added wilc3000 support for TS-TPC-7990 REV C WIFI
20180412	Debian 9 Stretch	debian-armhf-stretch-20180412.tar.bz2	Add support for SST26VF064BA, and IS25LP064A spi flashes Initial port to Debian Stretch
20180501	Debian 9 Stretch	debian-armhf-stretch-20180501.tar.bz2	Added support for TS-MINI-ADC
20181016	Debian 9 Stretch	debian-armhf-stretch-20181016.tar.bz2	Updated kernel to support the offboard SPI Chip select on TS-7990 REV C.
20200401	Debian 10 Buster	debian-armhf-buster-20200401.tar.bz2	Updated to Debian Buster (10) Updated to Linux 4.9.11 Added SILEX SDMAC+ support for TS-4900 REV E and TS-7970 REV F
20210210	Debian 10 Buster	debian-armhf-buster-20210210.tar.bz2	Updated to latest kernel revision with less verbose qcacld messages
20210526	Debian 10 Buster	debian-armhf-buster-20210526.tar.bz2	Kernel update to fix imx_thermal support when the board is already heat soaked past the passive cooling temp.
20211130	Debian 10 Buster	debian-armhf-buster-20211130.tar.bz2	Added WIFI fix for solo TS-4900 on fallback device tree
20230808	Debian 10 Buster	debian-armhf-buster-20230808.tar.bz2	add support for TS-TPC-7990 REV E
20211217	Debian 11 Bullseye	debian-armhf-bullseye-20211217.tar.bz2	Initial release of Debian Bullseye
20230807	Debian 11 Bullseye	debian-armhf-bullseye-20230807.tar.bz2	Updated bullseye image to add support for TS-TPC-7990 REV E
20230628	Debian 11 Bullseye	debian-armhf-bookworm-x11-20230628.tar.bz2	Initial release of Debian Bookworm Bumps to kernel 5.10
20230807	Debian 12 Bookworm	debian-armhf-bookworm-x11-20230807.tar.bz2	Added missing Silex firmware Fixed issue with Micrel phy on the TS-4900 solo add support for TS-TPC-7990 REV E
20230807	Debian 12 Bookworm	debian-armhf-bookworm-x11-20230807.tar.bz2	Added missing Silex firmware Fixed issue with Micrel phy on the TS-4900 solo add support for TS-TPC-7990 REV E
20240409	Debian 12 Bookworm	x11 headless minimal	Added apt locked version of wpa_supplicant to fix ath10k compatibility. Bumped to kernel v5.10.214-ts
20240909	Debian 12 Bookworm	x11 headless minimal	Bumped to kernel v5.10.224.1-ts Supports updated Accelerometer/Gyro on TS-TPC-7990 REV E

Android Changelog

Image	Changes
android-4.4.3-20150428.dd.bz2	Initial Release
android-4.4.3-20150629.dd.bz2	Fixed Bluetooth Fixed WIFI Added udhcpc on both ethernet ports Image ships rooted
android-7.1.1-tsimx6-tiwifi-20170831.dd.bz2 android-7.1.1-tsimx6-atmelwifi-20170818.dd.bz2	Update to 7.1.1 Added support for TS-7970, TS-TPC-7990 Split into two images, one for TI WIFI (TS-4900/TS-7970), one for Atmel WIFI (TS-TPC-7990)
android-7.1.1-tsimx6-tiwifi-20170831.dd.bz2	Fixed TS-TPC-8950 carrier board touchscreen calibration

Arch Linux Changelog

Image	Changes
arch-armhf-20180502.tar.bz2	Initial Release

Ubuntu Linux Changelog

Image date	Ubuntu Edition	Links	Changes
20160407	16.04 Xenial Xerus	ubuntu-armhf-16.04-20160407.tar.bz2	Initial Release
20160818	16.04 Xenial Xerus	ubuntu-armhf-16.04-20160818.tar.bz2	Bumped from 3.14.52 to 4.1.15 kernel. This adds support for the TS-TPC-7990. Added more common packages, mmc, can-utils, etc.
20170306	16.04 Xenial Xerus	ubuntu-armhf-16.04-20170306.tar.bz2	Updated ts4900-utils for final TS-7970/TS-TPC-7990 Added TS-TPC-7990 REV B support
20180221	16.04 Xenial Xerus	ubuntu-armhf-16.04-20180221.tar.bz2	Fixed TS-TPC-8950 touchscreen Updated to latest packages in apt repository Updated ts4900-utils to latest version, included fix for supercaps. Updated chromium browser's .desktop file to allow starting as root.
20190114	18.04 Bionic Beaver	ubuntu-armhf-18.04-20190114.tar.bz2	Update to Ubuntu 18.04 Updated to kernel 4.9
20190806	18.04 Bionic Beaver	ubuntu-armhf-18.04-20190806.tar.bz2	Updated to latest 4.9 kernel in git to add missing bluetooth driver
2011130	20.04 Focal Fossa	ubuntu-armhf-20.04-2011130.tar.bz2	Updated to Ubuntu 20.04 with Silex wifi support
20230807	23.04 Lunar Lobster	ubuntu-armhf-23.04-x11-20230807.tar.bz2	Initial release with Ubuntu 23.04 Updated to kernel 5.10
20240409	23.04 Lunar Lobster	x11 headless minimal	Added apt locked version of wpa_supplicant to fix ath10k compatibility. Bumped to kernel v5.10.214-ts
20240909	23.04 Lunar Lobster	x11 headless minimal	Bumped to kernel v5.10.224.1-ts Supports updated Accelerometer/Gyro on TS-TPC-7990 REV E
20240909	24.04 Noble Numbat	x11 headless minimal	Bumped to kernel v5.10.224.1-ts Supports updated Accelerometer/Gyro on TS-TPC-7990 REV E

Ubuntu Core Linux Changelog

Image	Changes
ubuntu-core-16-2016-12-22.img.bz2	Initial Release
ubuntu-core-16-2017-04-21.img.bz2	Fixed boot scripts to work with core updates Added support for the TS-4900 carrier board specific device trees. Added support for the TS-7970 Added support for the TS-TPC-7990 Updated Kernel Added ttyMAX* uart support Added fixes from our main Linux kernel to the RTC driver Fixed ethernet timing
ubuntu-core-16-2017-10-05.img.bz2	Added WIFI support
ubuntu-core-16-2019-09-12.img.bz2	Updated for latest SPI flash
ubuntu-core-16-2019-10-09.img.bz2	Bluetooth firmware included in the image

Product Notes

FCC Advisory

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

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

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

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

Limited Warranty

See our Terms and Conditions for more details.

Trademarks

Arm and Cortex are registered trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

[etcher-1] 1.0 ^1.1 ^1.2 embeddedTS is not affiliated with this tool. balenaEtcher version 1.5.101 tested in Windows 10 on 20220216

[win32-2] TS is not affiliated with this tool. Win32DiskImager 1.0.0 tested in Windows 10 on 20220216. Cannot handle compressed images, must first decompress disk image.

[ext2limit-3] The ext2 filesystem has a max file size limit as low at 16 GiB. This may cause issues for Image Capture.

[ext4warn-4] Use of ext4 may require additional options. U-Boot on some platforms does not support the 64-bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options -O ^64bit,^metadata_csum may need to be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed, nor are they needed for ext2 / 3.

[fatlimit-5] The FAT32 (supported by vfat in Linux) filesystem has a max file size limit of 4 GiB. This may cause issues for Image Capture.

[7zip-6] TS is not affiliated with this tool. 7-Zip 21.07 tested in Windows 10 on 20220222

[peazip-7] TS is not affiliated with this tool. PeaZip 7.2.0 tested in Windows 10 on 20220222

[8] Idle periods do not count towards the total throughput limitation.

[9] This is a requirement for half duplex MODBUS

[10] Set 1 to enable hardware reset on PUSH_SW low

[11] This pin is GPIO to just be used as an input for SPIUART0_RXD

[12] This pin is GPIO to just be used as an input for ttymxc3 rxd

[13] This pin is GPIO to just be used as an input for SPIUART2_RXD

[14] Route to GPIO to go nowhere

[15] Route to GPIO to go nowhere

[16] Route to GPIO to go nowhere

[17] The pad name does not often correspond with the functionality of the IO we use, but can be used to reference the pad in the CPU manual.

[18] This does not contain all of the functions possible for a pin, but the common functions as they are used on our off the shelf basebords. Consult the i.MX6 CPU Reference manual for a complete list.

[19] This pin is used to tune the LCD backlight through the PWM controller. On our baseboards where there is an LCD present this is connected to provide a sysfs tunable backlight. On other baseboards this is usable as a GPIO.

[20] This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #5, or pad "GPIO_5".

[21] This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #6, or pad "GPIO_6"

[22] This pin changed during the sampling program for the REV C boards. On rev A this was linux gpio #9, or pad "GPIO_9"

[lowatboot-23] 7.0 ^7.1 ^7.2 This GPIO stays LOW when power is applied and defaults to a low state until modified by software

[24] On our off the shelf baseboards this pin typically controls the 5V rail for USB peripherals. For custom designs this can optionally be connected to a FET to control USB peripherals power.

[25] This pin is dedicated to resetting offboard peripherals during a full reboot.

[26] On our off the shelf baseboards this is normally used to toggle power to the LCD if the baseboard uses an LCD.

[27] Used for onboard flash

[fpgai2c-28] 12.0 ^12.1 Used for communication with RTC and FPGA

[reva-29] 1.0 ^1.1 This pin is not an FPGA pin on PCB revisions after A

[30] See the Kernel documentation for more details

[31] When this trigger is set, a "gpio" file appears in the same directory which can be used to specify what GPIO to follow when it blinks

[32] See the Kernel documentation for more details

[33] EXT_RESET# is an open-drain input used to reboot the CPU.

[34] This is an output which can be manipulated in the #Syscon. This pin can optionally be connected to control a FET to a separate 5V rail for USB to allow software to reset USB devices.

[sdinterface-35] 3.0 ^3.1 ^3.2 ^3.3 ^3.4 ^3.5 This SD interface is the same one used by the MicroSD on the TS-4900. Only one can be used at a time.

[36] OFF_BD_RESET# is an output from the System-on-Module (SoM) that automatically sends a reset signal when the unit powers up or reboots. It can be connected to any IC on the base board that requires a reset.

[powerpins-37] 5.0 ^5.1 ^5.2 ^5.3 The 5V power pins should each be connected to a 5V source.

[38] This is used during production to boot to an offboard SPI flash. This pin should typically be left unconnected.

[power-threethree-39] 7.0 ^7.1 The TS-4900 regulates a 3.3V rail which can source up to 700mA. Designs should target a 300mA max if they intend to use other SoMs.

[40] This pin is used as a test point to verify the RAM has a correct voltage for debugging

[41] This pin is used as a test point for debugging

[42] CPU stops all throttling below this temperature

[43] CPU begins throttling until the cooling temperature

[44] CPU Max temperature. Linux will shut down to cool in u-boot at this temperature.

[1]

[2]

[1]

[2]

[3]

[4]

[5]

[1]

[2]

[1]

[1]

[2]

[3]

[4]

[5]

[6]

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[1]

[1]

[2]

[3]

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[1]

[2]

[3]

Search

TS-4900

Overview

Getting Started

Booting up the board

Get a Console

U-Boot

U-Boot Environment

U-Boot Commands

Modify Linux Kernel cmdline

Booting From NFS

Booting From USB

Update U-Boot

U-boot Recovery

U-boot Development

Fallback Capable U-boot scripts

Access U-boot Environment from Linux

Buildroot

Buildroot - Installing

Buildroot - Building

Buildroot - Cross Compiling

Buildroot - Configuring Network

Buildroot - Installing New Software

Buildroot - Setting Up SSH

Buildroot - Starting Automatically

Yocto

Getting Started with Yocto

First Boot

Yocto Networking

Yocto Wireless

Yocto Application Development

Configure Qt Creator IDE

Qt Creator Hello World

Yocto Hide Cursor

Yocto Startup Scripts

Custom Build Yocto

Debian

Debian 12 - Bookworm

Debian 12 - Getting Started

Debian 12 - Networking

Debian 12 - WIFI Client

Debian 12 - WIFI Access Point

Debian 12 - Installing New Software

Debian 12 - Setting up SSH

Debian 12 - Starting Automatically

Debian 12 - Cross Compiling

Debian 11 - Bullseye

Debian 11 - Getting Started

Debian 11 - Networking

Debian 11 - WIFI Client

Debian 11 - WIFI Access Point

Debian 11 - Installing New Software

Debian 11 - Setting up SSH

Debian 11 - Starting Automatically

Debian 11 - Cross Compiling

Debian 10 - Buster

Debian 10 - Getting Started

Debian 10 - Networking

Debian 10 - WIFI Client

Debian 10 - WIFI Access Point

Debian 10 - Installing New Software

Debian 10 - Setting up SSH

Debian 10 - Starting Automatically

Debian 10 - Cross Compiling

Debian 9 - Stretch

Debian 9 - Getting Started

Debian 9 - Networking

Debian 9 - WIFI Client

Debian 9 - WIFI Access Point

Debian 9 - Application Development

Debian 9 - Stretch Cross Compiling

Debian 9 - Installing New Software

Debian 9 - Setting up SSH

Debian 9 - Starting Automatically

Debian 8 - Jessie

Debian 8 - Getting Started

Debian 8 - Networking

Debian 8 - WIFI Client

Debian 8 - WIFI Access Point

Debian 8 - Application Development