TS-8820-4100
 | |
| Product Page | |
| Image Gallery | |
| Documentation | |
|---|---|
| Schematic | |
| Software Support | |
| TS-8820 source directory | |
| Dimensions (in enclosure) | |
| 6.35 inches (tall) by 7.714 inches (wide including DB9) by 1.14 inches (deep) |
Overview
The TS-8820-BOX is a rugged, feature-rich TS-SOCKET based baseboard and System-on-Module (SoM) combination for industrial applications. The TS-8820-BOX is powered by the TS-4100, TS-4700, TS-4710, TS-4720 or TS-4800 System-on-Module devices. The TS-8820-BOX enclosure exposes all of the available I/O on rugged screw terminals while protecting the SoM and other sensitive electronics. The TS-8820-BOX a tough, durable, flexible, powerful, and affordable industrial process control platform.
The TS-4100 is a TS-SOCKET System-on-Module (SoM) designed for low power applications. It is based around an NXP i.MX6UL 696 MHz CPU with 512 MB or 1GB DDR3 RAM. The TS-4100 can be ordered with soldered down WiFi which includes built in Bluetooth 4.0LE. There is also support for USB Gadget via a micro USB AB OTG connector and eMMC flash for a robust soldered down flash solution.
TS-4100
See the TS-4100 page for functionality regarding the CPU, FPGA, and OS.
|
NXP i.MX6ul 696 MHz Cortex-A7 (ARMv7) |
Getting Started
A Linux PC is recommended for development, and will be assumed for this documentation. For users in Windows or OSX we recommend virtualizing a Linux PC. Most of our platforms run Debian and if there is no personal distribution preference this is what we recommend for ease of use.
Virtualization
Suggested Linux Distributions
It may be possible to develop using a Windows or OSX system, but this is not supported. Development will include accessing drives formatted for Linux and often Linux based tools.
Booting up the board
The TS-8820-4100 accepts 10 V to 30 V DC connected directly to the terminal block inputs, as well as IEEE 802.3af PoE. See the "Power Supply" section for detailed information on powering the device.
Power input to the TS-4100 TS-SOCKET requires a single 5 V source from the baseboard (which may be regulated from other voltage ranges). Refer to the TS-SOCKET Connector section for information on power pins.
The TS-4100 can also be powered standalone from 5 V via the micro USB AB port labeled "P1" when in standalone and not attached to a baseboard. The "P1" connector is mechanically locked out on many of our baseboards to prevent powering the device from multiple sources. For more information on how to operate the TS-4100 in standalone mode see section on Standalone Mode.
Once power is applied to the system, there will be output on the debug console port. The connecting to a console section of the manual provides information on getting the serial console connected. The first output is from U-Boot and will resemble the following when booting from SD card:
U-Boot 2016.03-00367-gb3ce405827 (Jul 02 2019 - 16:40:10 -0700)
CPU: Freescale i.MX6UL rev1.1 at 396 MHz
Reset cause: POR
Board: Technologic Systems TS-4100
FPGA: Rev 11
Silab: Rev 2
I2C: ready
DRAM: 1 GiB
MMC: FSL_SDHC: 0, FSL_SDHC: 1
Baseboard ID: 0x8
Baseboard Rev: 0
Net: FEC0 [PRIME]
Press Ctrl+C to abort autoboot in 1 second(s)
starting USB...
USB0: USB EHCI 1.00
scanning bus 0 for devices... 1 USB Device(s) found
USB1: USB EHCI 1.00
scanning bus 1 for devices... 1 USB Device(s) found
scanning usb for storage devices... 0 Storage Device(s) found
No storage devices, perhaps not 'usb start'ed..?
Booting from the SD card ...
** File not found /boot/boot.scr **
** File not found /boot/ts4100-fpga.vme **
29205 bytes read in 146 ms (195.3 KiB/s)
8 detected
5244088 bytes read in 390 ms (12.8 MiB/s)
Kernel image @ 0x80800000 [ 0x000000 - 0x5004b8 ]
## Flattened Device Tree blob at 83000000
Booting using the fdt blob at 0x83000000
Using Device Tree in place at 83000000, end 8300a214
Starting kernel ...
| Note: | The "*** Warning - bad CRC, using default environment" message can be safely ignored when the unit is first booted. This means that no environment variables have been saved to disk, and U-Boot is falling back to the default. If "env save" is run, this will save the environment to disk, and this message will go away unless there are further issues. |
The default U-Boot boot process will check for a bootable USB drive, and then will check the "SD Boot" jumper state if it exists. If the "SD boot" jumper is set, it will boot to the Linux on the SD card, otherwise it will boot to the eMMC. Details about the bootup process, features, and other U-Boot information can be found in the U-Boot sections.
Get a Console
The TS-8820-4100 offers an RS-232 level console UART on the DB-9 connector. The console UART runs at 115200 baud, 8n1 (8 data bits, no parity, 1 stop bit), with no flow control.
By default, all system messages and a Linux login prompt are output on this interface. It is a "DTE" port, meaning it is equivalent to the same port on a PC/Desktop/Workstation. Due to this, a NULL MODEM cable is required to interface from a host PC to the TS-8820-4100. This port can be used for application purposes, for example to interface with a "DCE" serial device. However the login prompt and kernel information must be disabled. Additionally, note that it is not possible to disable the U-Boot output on this port; any connected devices must be able to handle this text output safely.
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.
- Connect the console serial terminal cable
- Connect the Ethernet cable if applicable.
- Monitor the device bootup using a terminal emulator connected to the serial console port to verify that the board is operating properly
See the TS-4100 page for more details on dealing with the functionality of the CoM.
U-Boot
| Note: | This section is incomplete at this time. |
This platform includes U-Boot as the bootloader to load and boot the full operating system. The i.MX6UL processor loads U-Boot from the eMMC flash at power-on. U-Boot allows booting images from the microSD, eMMC, NFS, or USB. U-Boot is a general purpose bootloader that is capable of booting into common Linux distributions, Android, QNX, or others.
On a normal boot, output from U-Boot will be similar to the following:
U-Boot 2016.03-00367-gb3ce405827 (Jul 02 2019 - 16:40:10 -0700)
CPU: Freescale i.MX6UL rev1.1 at 396 MHz
Reset cause: POR
Board: Technologic Systems TS-4100
FPGA: Rev 11
Silab: Rev 2
I2C: ready
DRAM: 1 GiB
MMC: FSL_SDHC: 0, FSL_SDHC: 1
Baseboard ID: 0x8
Baseboard Rev: 0
Net: FEC0 [PRIME]
Press Ctrl+C to abort autoboot in 1 second(s)
starting USB...
USB0: USB EHCI 1.00
scanning bus 0 for devices... 1 USB Device(s) found
USB1: USB EHCI 1.00
scanning bus 1 for devices... 1 USB Device(s) found
scanning usb for storage devices... 0 Storage Device(s) found
No storage devices, perhaps not 'usb start'ed..?
Booting from the SD card ...
** File not found /boot/boot.scr **
** File not found /boot/ts4100-fpga.vme **
29205 bytes read in 146 ms (195.3 KiB/s)
8 detected
5244088 bytes read in 390 ms (12.8 MiB/s)
Kernel image @ 0x80800000 [ 0x000000 - 0x5004b8 ]
## Flattened Device Tree blob at 83000000
Booting using the fdt blob at 0x83000000
Using Device Tree in place at 83000000, end 8300a214
Starting kernel ...
When running standalone, the TS-4100 will default to booting from eMMC. This behavior can be changed by modifying the U-Boot environment variable "force_jpsdboot". Normally this variable does not exist in the U-Boot environment, if it does exist, setting it to a value of 1 will force U-Boot to attempt to boot from microSD. If it is set to a value of 0, then U-Boot will attempt to boot from eMMC. Additionally, running U-Boot commands are used direct booting to another source such as NFS, USB, or microSD.
Many of our compatible baseboards offer an "SD Boot" jumper to control the behavior between SD and eMMC. See the specific baseboard manual for the combination being used for more detailed information. If designing a custom baseboard, we recommend reviewing our custom baseboard design recommendations for better controlling boot flow with U-Boot.
Entering U-Boot Shell
| Note: | This section needs adjustment for the TS-8820 specifics |
The U-Boot shell is a powerful tool. It allows modification of the environment, as well as the ability to run commands directly.
When the TS-4100 is booted standalone, a prompt is provided by U-Boot to press "ctrl+c" followed by a 1 second window. If "ctrl+c" is found incoming on the serial terminal within this time window then U-Boot will drop to its shell. This behavior can be modified by setting the U-Boot environment variable "force_bootdelay". Normally this variable does not exist in U-Boot environment, if it does, it will force the timeout for pressing "ctrl+c" to be however many seconds the variable is set to. If it is set to 0, then the "ctrl+c" prompt is skipped.
| Note: | Use caution when setting "force_bootdelay", a value of 0 means it is no longer possible to enter the U-Boot shell without booting the device on a compatible baseboard that has a "U-Boot" jumper! |
On our compatible baseboards or custom designed baseboards there are two ways to break in to the U-Boot shell. Note that some compatible baseboards may still offer a prompt as outlined above. See the specific baseboard manual for the combination being used for more detailed information.
The baseboard has a "U-Boot" jumper. When set, this will cause U-Boot to read a script file from an attached USB mass storage device before dropping to the U-Boot shell. When the jumper is not set, the unit will boot as normal. See our custom baseboard design recommendations for information on how the U-Boot jumper should be set up in order to be supported by our default U-Boot configuration.
The baseboard offers a push switch which is broken out from pin 9 on CN1 of the TS-4100. This button can be held down before applying power, and at least 5 seconds after power is applied.
This allows for out of the box functionality and customized production via a USB drive. In order to provide increased security, the push switch entry to U-Boot can be disabled via the U-Boot environment variable rstuboot. The following U-Boot commands can be used to disable the push switch check, thereby preventing it from being able to enter the U-Boot shell.
env set rstuboot 0
env save
Removing the rstuboot environment variable, or setting it to a 1, will re-enable the ability for the push switch to interrupt U-Boot and drop to its shell. See our custom baseboard design recommendations for information on how the push switch should be set up in order to be supported by our default U-Boot configuration.
On baseboards that support both a jumper and the push switch, disabling the push switch will still allow the jumper method of entering the U-Boot shell.
U-Boot Environment
The eMMC flash contains both the U-Boot executable binary and U-Boot environment. Our default build has 2 MiB of environment space which can be used for variables and boot scripts. The following commands are examples of how to manipulate the U-Boot environment:
# Print all environment variables
env print -a
# Sets the variable bootdelay to 5 seconds
env set bootdelay 5;
# Variables can also contain commands
env set hellocmd 'led red on; echo Hello world; led green on;'
# Execute commands saved in a variable
env run hellocmd;
# Commit environment changes to the SPI flash
# Otherwise changes are lost
env save
# Restore environment to default
env default -a
# Remove a variable
env delete emmcboot
U-Boot Commands
# The most important command is
help
# This can also be used to see more information on a specific command
help i2c
# This is a command added to U-Boot by TS to read the baseboard ID on our
# System on Module devices
bbdetect
echo ${baseboard} ${baseboardid}
# The echo will return something similar to:
# TS-8390 2
# Boots into the binary at $loadaddr. The loaded file needs to have
# the U-Boot header from mkimage. A uImage already contains this.
bootm
# Boots into the binary at $loadaddr, skips the initrd, specifies
# the FDT addrress so Linux knows where to find the device tree
bootm ${loadaddr} - ${fdtaddr}
# Boot a Linux zImage loaded at $loadaddr
bootz
# Boot in to a Linux zImage at $loadaddr, skip initrd, specifies
# the FDT address to Linux knows where to find the device tree
bootz ${loadaddr} - ${fdtaddr}
# Get a DHCP address
dhcp
# This sets ${ipaddr}, ${dnsip}, ${gatewayip}, ${netmask}
# and ${ip_dyn} which can be used to check if the dhcp was successful
# These commands are used for scripting:
false # do nothing, unsuccessfully
true # do nothing, successfully
# This command can set fuses in the processor
# Setting fuses can brick the unit, will void the warranty,
# and should not be done in most cases
fuse
# GPIO can be manipulated from U-Boot. Keep in mind that the IOMUX
# in U-Boot is only setup enough to boot the device, so not all pins will
# be set to GPIO mode out of the box. Boot to the full operating system
# for more GPIO support.
# GPIO are specified in bank and IO in this manual. U-Boot uses a flat numberspace,
# so for bank 2 DIO 25, this would be number (32*1)+25=89
# The formula thus being (32*(bank-1)+dio)=flattened_dio
# Note that on some products, bank 1 is the first bank
# Set 2_25 low
gpio clear 83
# Set 2_25 high
gpio set 83
# Read 2_25
gpio input 83
# Control LEDs
led red on
led green on
led all off
led red toggle
# This command is used to copy a file from most devices
# Load kernel from SD
load mmc 0:1 ${loadaddr} /boot/uImage
# Load Kernel from eMMC
load mmc 1:1 ${loadaddr} /boot/uImage
# Load kernel from USB
usb start
load usb 0:1 ${loadaddr} /boot/uImage
# Load kernel from SATA
sata init
load sata 0:1 ${loadaddr} /boot/uImage
# View the FDT from U-Boot
load mmc 0:1 ${fdtaddr} /boot/imx6q-ts4900.dtb
fdt addr ${fdtaddr}
fdt print
# It is possible to blindly jump to any memory location
# This is similar to bootm, but it does not require
# the use of the U-Boot header
load mmc 0:1 ${loadaddr} /boot/custombinary
go ${loadaddr}
# Browse fat, ext2, ext3, or ext4 filesystems:
ls mmc 0:1 /
# Access memory like devmem in Linux, read/write arbitrary memory
# using mw and md
# write
mw 0x10000000 0xc0ffee00 1
# read
md 0x10000000 1
# Test memory.
mtest
# Check for new SD card
mmc rescan
# Read SD card size
mmc dev 0
mmcinfo
# Read eMMC Size
mmc dev 1
mmcinfo
# The NFS command is like 'load', but used over the network
dhcp
env set serverip 192.168.0.11
nfs ${loadaddr} 192.168.0.11:/path/to/somefile
# Test ICMP
dhcp
ping 192.168.0.11
# Reboot
reset
# SPI access is through the SF command
# Be careful with sf commands since
# this is where U-Boot and the FPGA bitstream exist
# Improper use can render the board unbootable
sf probe
# Delay in seconds
sleep 10
# Load HUSH scripts that have been created with mkimage
load mmc 0:1 ${loadaddr} /boot/ubootscript
source ${loadaddr}
# Most commands have return values that can be used to test
# success, and HUSH scripting supports comparisons like
# test in Bash, but much more minimal
if load mmc 1:1 ${fdtaddr} /boot/uImage;
then echo Loaded Kernel
else
echo Could not find kernel
fi
# Commands can be timed with "time"
time sf probe
# Print U-Boot version/build information
version
Modify Linux Kernel cmdline
The Linux kernel cmdline can be customized by modifying the cmdline_append variable. If new arguments are added, the existing value should also be included with the new arguments.
env set cmdline_append rw rootwait console=ttymxc0,115200 quiet
env save
The kernel command line can also be modified from from within Linux by creating a U-Boot script. From the Linux shell prompt run the following commands to install the necessary tools and create the script:
apt-get update && apt-get install u-boot-tools -y
echo "env set cmdline_append rw rootwait console=ttymxc0,115200 quiet" > /boot/boot.source
mkimage -A arm -T script -C none -n 'tsimx6ul boot script' -d /boot/boot.source /boot/boot.scr
The boot.source includes the plain text commands to be run in U-Boot on startup. The mkimage tool adds a checksum and header to the output file which then can be loaded by U-Boot. The .scr file should not be edited directly.
By default, every boot to SD, eMMC, and NFS will look for the file "/boot/boot.scr" and attempt to load and run it if it exists. This allows for modification of the boot process dynamically every boot without having to enter the U-Boot shell and modify it.
Linux NFS Boot
U-Boot's NFS support can be used to load a kernel, device tree binary, and root filesystem. The default scripts include an example NFS boot script. Because of the way U-Boot tries to infer server data, the script we use will bypass this, making it more straightforward to use an NFS root that will not be heavily dependent on a particular network configuration.
# Set this to your NFS server IP
env set nfsip 192.168.0.1
# Set this to your NFS root path
env set nfsroot /path/to/nfs/rootfs/
env save
To boot to NFS root once the server details are set:
# Boot to NFS once
run nfsboot;
# To make the NFS boot the persistent default
env set bootcmd run nfsboot;
env save
| Note: | 'bootcmd' is used to test for whether the system should stop at the U-Boot shell or continue, the above will make it difficult to get back to the U-Boot shell as it will always attempt to boot regardless of jumper status. |
On the TS-4100, U-Boot will only boot to the network from the first physical port. The port that Linux considers to be "eth1".
Linux USB Boot
| Note: | This section needs adjustment for the TS-8820 specifics |
In standalone mode, this process is attempted on every boot unless it is disabled. It can be disabled by modifying the U-Boot environment variable "usbboot". If "usbboot" is set to 0 then this step will be bypassed. It is enabled by default to allow for a custom production process to be used. If the U-Boot shell is entered, this process can always be manually started with the command 'run usbprod'.
By default, U-Boot will attempt to read a U-Boot script from a USB drive when the U-Boot jumper is set or the reset button is enabled and held down. It copies "/tsinit.scr" into memory and jumps in to the script. To make a bootable drive, create a single ext3 partition on a USB drive and unpack the rootfs tarball located here
By default, U-Boot will attempt to read a U-Boot script from a USB drive on every bootup. This process copies /tsinit.scr from the first partition of the USB drive into memory and jumps in to the script. If the drive or script do not exist, then this process is bypassed and U-Boot will continue its boot flow.
This process is attempted on every boot unless it is disabled. It can be disabled by modifying the U-Boot environment variable usbboot. If usbboot is set to 0 then this step will be bypassed on normal boot cycles. It is enabled by default to allow for a custom production process to be used.
If the U-Boot shell is entered by holding the push switch or using the U-Boot jumper (on baseboards with either a push switch or U-Boot jumper), this process will always run before dropping to the U-Boot shell regardless of the state of the usbboot variable. If the U-Boot shell is entered by pressing ctrl+c (on boaseboards without a U-Boot jumper or TS-4100 standalone), then this process is never run since autoboot is aborted and the shell is immediately entered. In this state, the USB boot process can always be manually started with the command run usbprod.
For information on creating a USB drive to write existing images to either SD and/or eMMC, see the section on our custom production process for more details on the process.
To make a bootable USB drive that boots in to the same environment as SD or eMMC, create a single ext3 partition on a USB drive and unpack the rootfs tarball located here.
Additionally, a U-Boot script file, /tsinit.scr, must be created and placed in the root folder of this partition. In order to do this, a script must be created and converted to the U-Boot .scr format. This process requires a set of U-Boot specific tools. These tools are available on most every Linux distribution, the instructions below are for Debian, either on a host PC or on the device itself. See the package installation documentation for other respective distributions.
Install U-Boot tools in Debian
apt-get update && apt-get install u-boot-tools -y
Create the file "tsinit.source" in the root of the USB drive with the Linux filesystem:
# Prepare with:
# mkimage -A arm -T script -C none -n 'imx6ul usb' -d tsinit.source tsinit.scr
# DO NOT MANUALLY EDIT THE .scr FILE
if load usb 0:1 ${loadaddr} /boot/ts${model}-fpga.vme;
then fpga load 0 ${loadaddr} ${filesize};
fi;
if load usb 0:1 ${fdtaddr} /boot/imx6ul-ts${model}-${baseboardid}.dtb;
then echo "${baseboardid} detected;"
else echo "Booting default device tree";
load usb 0:1 ${fdtaddr} /boot/imx6ul-ts${model}.dtb;
fi;
load usb 0:1 ${loadaddr} /boot/zImage;
setenv bootargs root=/dev/sda1 rootwait rw ${cmdline_append} bbid=0x${baseboardid} bbrev=0x${baseboardrev};
run silowaitcharge;
bootz ${loadaddr} - ${fdtaddr};
fi;
Then in the same directory generate the tsinit.scr file:
mkimage -A arm -T script -C none -n 'imx6ul usb' -d tsinit.source tsinit.scr
Update U-Boot
| WARNING: | Installing a custom U-Boot is not recommended and may cause the device to fail to boot. |
The TS-4100 uses slightly different U-Boot binaries for the 512 MB and 1 GB RAM variants. This is due to different DDR timing that needs to be set up at the start of U-Boot. When updating U-Boot, be sure to use the script that exists in U-Boot discussed below as it will use the correct file name and will reduce any potential issues
The latest U-Boot binary can be downloaded from the TS-4100 FTP site. Copy these files to /boot/ on the 1st partition of the SD card (or eMMC). The U-Boot binary can be updated by inserting that SD card in to the TS-4100, setting the jumpers to boot from SD, power up the unit, and enter the U-Boot shell. At the U-Boot prompt, the following command can be used:
run update-uboot
The above script will use the /boot/u-boot-${imx_type}.imx file from the SD card or eMMC, depending on the state of the SD Boot jumper.
Note that when running the TS-4100 standalone, the "update-uboot" command will default to searching the eMMC. Setting the environment variable "jpsdboot" to "on" (do not save the environment to disk otherwise it may cause booting issues later!), and then running the 'run update-uboot' command will cause U-Boot to look in "/boot" on the first SD card partition for the update files necessary.
U-Boot Development
We do provide our U-Boot sources, but we do not recommend rebuilding a custom U-Boot binary as it can leave the system in an unbootable state.
If proceeding with building a custom U-Boot, use the "tsimx_v2016.03_4.1.15_2.0.0_ga" branch from our github repo: https://github.com/embeddedTS/u-boot-imx this can be executed with the following command:
git clone https://github.com/embeddedTS/u-boot-imx.git -b tsimx_v2016.03_4.1.15_2.0.0_ga u-boot-ts4100When compiling, we recommend using ONLY this cross-compiler, the use of any other compiler may cause issues or may leave the system in an unbootable state! Specifically, we have experienced RAM problems when using a more recent cross compiler to build this version of U-Boot. The tarball can be extracted with the following:
mkdir /opt/toolchains/ts4100/
tar -xf tsimx6ul-glibc-gnueabihf-4.9.4.tar.xz -C /opt/toolchains/ts4100/
Once the tarball has been properly extracted set up the following variables and run the build script:
export ARCH=arm
export CROSS_COMPILE=/path/to/folder/bin/arm-tsimx6ul-linux-gnueabihf-
After the environment variables have been set up as shown above the build is now ready to be executed:
cd /path/to/u-boot-imx
./build-imx6ul.sh ts4100
This will output binaries for 1 GB and 512 MB RAM variants in "/u-boot-imx/out/" that can be written to the device using the steps in Update U-Boot.
| Note: | If the following error message is received: "error while loading shared libraries: libmpfr.so.4: cannot open shared object file:" create the following symbolic link in Debian:
sudo ln -s /usr/lib/x86_64-linux-gnu/libmpfr.so.6 /usr/lib/x86_64-linux-gnu/libmpfr.so.4
|
POST
The TS-4100 U-Boot includes a simple POST test. This is normally used in production to verify basic functionality rapidly before continuing to more thorough testing. By default, this is not enabled on every boot, but it can be added via U-Boot scripting if there is a need for additional confidence in the application. The POST test quickly verifies basic functionality of: USB, RTC (if present), Ethernet PHY, WiFi/BT module (if present), eMMC (see warning below), RAM, and the supervisory microcontroller.
The post test can be run with the following command in U-Boot:
post
| WARNING: | The 'post' command has an optional "-d" argument; when this argument is passed it does a write and readback test of the eMMC and any other soldered down flash media on the TS-4100 or baseboards which is DESTRUCTIVE to the data on the disk! Note that it will not modify the boot sector contents of the eMMC which is needed by U-Boot. The eMMC chip is still tested for basic functionality without the argument passed, but no data is read or written from the disk itself. |
Debian
Debian Stretch(9)
Getting Started
The stock image uses a Debian Stretch distribution and Linux kernel version 4.9. The latest image can be downloaded below.
This image can then be written to a microSD card or the on-board eMMC flash in order to be booted on the TS-4100.
Debian Networking
| Note: | The first physical port on the TS-4100 (or on Baseboards with a single port) is given the name "eth1", while the second port is "eth0". |
By default, Debian Stretch does not configure or bring up any interfaces.
Debian can automatically set up the networking based on the contents of "/etc/network/interfaces.d/" files. For example, to enable DHCP for "eth0" by default on startup:
echo "auto eth0
iface eth0 inet dhcp" > /etc/network/interfaces.d/eth0
To set up a static IP:
echo "auto eth0
iface eth0 inet static
address 192.168.0.50
netmask 255.255.255.0
gateway 192.168.0.1" > /etc/network/interfaces.d/eth0
echo "nameserver 1.1.1.1" > /etc/resolv.conf
To make this take effect immediately for either option:
service networking restart
To configure other interfaces, replace "eth0" with the other network device name. Some interfaces may use predictable interface names. For example, the traditional name for an ethernet port might be "eth1", but some devices may use "enp1s0" for PCIe, or "enx00D069C0FFEE" (the MAC address appended) for USB ethernet interfaces. Run 'ifconfig -a' or 'ip a' to get a complete list of interfaces, including the ones that are not configured.
Debian Wi-Fi Client
| Note: | The latest image for this platform as of April 28th, 2022 has known issues with the Wi-Fi driver due to incompatibility with cfg80211 powersave modes.
If using Wi-Fi, it is strongly recommended to bring up the Wi-Fi interface, and then run This issue will be addressed in future images and has already been addressed in our kernel sources. We will continue to provide updates as we receive them from the Wi-Fi module manufacturer. |
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 151790fab3bf3a1751a269618491b54984e192aa19319fc667397d45ec8dee5bTo have this take effect immediately:
service networking restart
For more information on configuring Wi-Fi, see Debian's guide here.
Debian Wi-Fi Access Point
| Note: | The latest image for this platform as of April 28th, 2022 has known issues with the Wi-Fi driver due to incompatibility with cfg80211 powersave modes.
If using Wi-Fi, it is strongly recommended to bring up the Wi-Fi interface, and then run This issue will be addressed in future images and has already been addressed in our kernel sources. We will continue to provide updates as we receive them from the Wi-Fi module manufacturer. |
This section will discuss setting up the WiFi device as an access point that is bridged to an ethernet port. That is, clients can connect to the AP and will be connected to the ethernet network through this network bridge. The ethernet network must provide a DHCP server; this will be passed through the bridge to WiFi client devices as they connect.
It is also possible to run a DHCP client on the platform itself. In this case the hostapd.conf file needs to be set up without bridging and a DHCP server needs to be configured. Refer to Debian's documentation for more details on DHCP server configuration.
The 'hostapd' utility is used to manage the access point of the device. This is usually installed by default, but can be installed with:
apt-get update && apt-get install hostapd -y
| Note: | The install process may start an unconfigured 'hostapd' process. This process must be killed before moving forward. |
Modify the file "/etc/hostapd/hostapd.conf" to have the following lines:
ssid=YourWiFiName
wpa_passphrase=Somepassphrase
interface=wlan0
bridge=br0
auth_algs=3
channel=7
driver=nl80211
hw_mode=g
logger_stdout=-1
logger_stdout_level=2
max_num_sta=5
rsn_pairwise=CCMP
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP CCMP
| Note: | Refer to the kernel's hostapd documentation for more wireless configuration options. |
The access point can be started and tested by hand:
hostapd /etc/hostapd/hostapd.conf
Systemd auto-start with bridge to eth0
It is possible to configure the auto-start of 'hostapd' through systemd. The configuration outlined below will set up a bridge with "eth0", meaning the Wi-Fi connection is directly connected to the ethernet network. The ethernet network is required to have a DHCP server present and active on it to assign Wi-Fi clients an IP address. This setup will allow Wi-Fi clients access to the same network as the ethernet port, and the bridge interface will allow the platform itself to access the network.
Set up hostapd
First, create the file "/etc/systemd/system/hostapd_user.service" with the following contents:
[Unit]
Description=Hostapd IEEE 802.11 AP
Wants=network.target
Before=network.target
Before=network.service
After=sys-subsystem-net-devices-wlan0.device
After=sys-subsystem-net-devices-br0.device
BindsTo=sys-subsystem-net-devices-wlan0.device
BindsTo=sys-subsystem-net-devices-br0.device
[Service]
Type=forking
PIDFile=/run/hostapd.pid
ExecStart=/usr/sbin/hostapd /etc/hostapd/hostapd.conf -P /run/hostapd.pid -B
[Install]
WantedBy=multi-user.target
Then enable this in systemd:
systemctl enable hostapd_user.service
systemctl enable systemd-networkd
Set up bridging
Create the following files with the listed contents.
"/etc/systemd/network/br0.netdev"
[NetDev]
Name=br0
Kind=bridge
"/etc/systemd/network/br0.network"
[Match]
Name=br0
[Network]
DHCP=yes
"/etc/systemd/network/bridge.network"
[Match]
Name=eth0
[Network]
Bridge=br0
Debian Wi-Fi Concurrent Client / Access Point
| Note: | The latest image for this platform as of April 28th, 2022 has known issues with the Wi-Fi driver due to incompatibility with cfg80211 powersave modes.
If using Wi-Fi, it is strongly recommended to bring up the Wi-Fi interface, and then run This issue will be addressed in future images and has already been addressed in our kernel sources. We will continue to provide updates as we receive them from the Wi-Fi module manufacturer. |
The Wi-Fi device on this platform supports concurrent operation of client and access point (STA and AP). Please see the "Wi-Fi Client" section above first to connect the Wi-Fi module, in STA mode, to an external AP. This demo showcases the Wi-Fi module starting its own AP mode via hostapd with a simple static IP address while also being concurrently connected to a separate AP.
The 'hostapd' utility is used to manage the access point of the device. This is usually installed by default, but can be installed with:
apt-get update && apt-get install hostapd -y
| Note: | The install process may start an unconfigured 'hostapd' process. This process must be killed before moving forward. |
Modify the file /etc/hostapd/hostapd.conf to have the following lines:
ssid=YourWiFiName
wpa_passphrase=Somepassphrase
interface=p2p0
auth_algs=3
channel=<channel>
driver=nl80211
hw_mode=g
logger_stdout=-1
logger_stdout_level=2
max_num_sta=5
rsn_pairwise=CCMP
wpa=2
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP CCMP
| Note: | The channel used for AP must match the channel the STA is using! Be sure to set 'channel=...' in the above file to a proper channel number. |
| Note: | Refer to the kernel's hostapd documentation for more wireless configuration options. |
In order for the concurrent modes to work, a separate virtual wireless device must first be created. Note that hostapd.conf above lists interface=p2p0, a second interface with this name must be created:
iw wlan0 interface add p2p0 type managed
The access point can then be started and tested by hand:
hostapd /etc/hostapd/hostapd.conf &
An IP address can be set to p2p0:
ifconfig p2p0 192.168.0.1
From this point, other Wi-Fi clients can connect to the SSID YourWiFiName with the WPA2 key Somepassphrase with a static IP in the range of 192.168.0.0/24, and will be able to access the platform at 192.168.0.1. More advanced configurations are also possible, including bridging, routing/NAT, or simply separate networks with the Wi-Fi module connecting to a network and hosting its own private network with DHCP.
Debian Application Development
Debian Stretch Cross Compiling
Debian Stretch provides cross compilers from the Debian apt repository archive for Debian Stretch. An install on a workstation can build for the same release on other architectures. A Linux desktop or laptop PC, virtual machine, or chroot will need to be used for this. Debian Stretch for a workstation can be downloaded from here.
From a Debian workstation (not the target), run these commands to set up the cross compiler:
# Run "lsb_release -a" and verify Debian 9.X is returned. These instructions are not
# expected to work on any other version or distribution.
su root
# Not needed for the immediate apt-get install, but used
# so we can install package:armhf for cross compiling
dpkg --add-architecture armhf
apt-get update
apt-get install curl build-essential crossbuild-essential-armhf -y
This will install a toolchain that can be used with the prefix "arm-linux-gnueabihf-". The standard GCC tools will start with that name, eg "arm-linux-gnueabihf-gcc".
The toolchain can now compile a simple hello world application. Create hello-world.c on the Debian workstation:
#include <stdio.h>
int main(){
printf("Hello World\n");
}
To compile this:
arm-linux-gnueabihf-gcc hello-world.c -o hello-world
file hello-world
This will return that the binary created is for ARM. Copy this to the target platform to run it there.
Debian Stretch supports multiarch which can install packages designed for other architectures. On workstations this is how 32-bit and 64-bit support is provided. This can also be used to install armhf packages on an x86 based workstation.
This cross compile environment can link to a shared library from the Debian root. The package would be installed in Debian on the workstation to provide headers and libraries. This is included in most "-dev" packages. When run on the arm target it will also need a copy of the library installed, but it does not need the -dev package.
apt-get install libcurl4-openssl-dev:armhf
# Download the simple.c example from curl:
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
# After installing the supporting library, curl will link as compiling on the unit.
arm-linux-gnueabihf-gcc simple.c -o simple -lcurl
Copy the binary to the target platform and run on the target. This can be accomplished with network protocols like NFS, SCP, FTP, etc.
If any created binaries do not rely on hardware support like GPIO or CAN, they can be run using 'qemu'.
# using the hello world example from before:
./hello-world
# Returns Exec format error
apt-get install qemu-user-static
./hello-world
Debian Installing New Software
Debian provides the apt-get system which allows management of pre-built applications. The apt tools require a network connection to the internet in order to automatically download and install new software. The update command will download a list of the current versions of pre-built packages.
apt-get update
A common example is installing Java runtime support for a system. Find the package name first with search, and then install it.
root@ts:~# apt-cache search openjdk default-jdk - Standard Java or Java compatible Development Kit default-jdk-doc - Standard Java or Java compatible Development Kit (documentation) default-jdk-headless - Standard Java or Java compatible Development Kit (headless) default-jre - Standard Java or Java compatible Runtime default-jre-headless - Standard Java or Java compatible Runtime (headless) jtreg - Regression Test Harness for the OpenJDK platform libreoffice - office productivity suite (metapackage) openjdk-8-dbg - Java runtime based on OpenJDK (debugging symbols) openjdk-8-demo - Java runtime based on OpenJDK (demos and examples) openjdk-8-doc - OpenJDK Development Kit (JDK) documentation openjdk-8-jdk - OpenJDK Development Kit (JDK) openjdk-8-jdk-headless - OpenJDK Development Kit (JDK) (headless) openjdk-8-jre - OpenJDK Java runtime, using Hotspot JIT openjdk-8-jre-headless - OpenJDK Java runtime, using Hotspot JIT (headless) openjdk-8-jre-zero - Alternative JVM for OpenJDK, using Zero/Shark openjdk-8-source - OpenJDK Development Kit (JDK) source files uwsgi-app-integration-plugins - plugins for integration of uWSGI and application uwsgi-plugin-jvm-openjdk-8 - Java plugin for uWSGI (OpenJDK 8) uwsgi-plugin-jwsgi-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8) uwsgi-plugin-ring-openjdk-8 - Closure/Ring plugin for uWSGI (OpenJDK 8) uwsgi-plugin-servlet-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8) java-package - Utility for creating Java Debian packages
In this case, the wanted package will likely be the "openjdk-8-jre" package. Names of packages can be found on Debian's wiki pages or the packages site.
With the package name apt-get install can be used to install the prebuilt packages.
apt-get install openjdk-8-jre
# More than one package can be installed at a time.
apt-get install openjdk-8-jre nano vim mplayer
For more information on using apt-get refer to Debian's documentation here.
Debian Setting up SSH
To install the SSH server, install the package with apt-get:
apt-get install openssh-server
Debian Stretch by default disallows logins directly from the user "root". Additionally, SSH will not allow remote connections without a password or valid SSH key pair. This means in order to SSH to the device, a user account must first be created, and a password set:
useradd --create-home --shell /bin/bash newuser
passwd newuser
After this setup it is now possible to connect to the device as user "newuser" from a remote PC supporting SSH. On Linux/OS X this is the "ssh" command, or from Windows using a client such as PuTTY.
Debian Starting Automatically
A systemd service can be created to start up headless applications. Create a file in /etc/systemd/system/yourapp.service
[Unit]
Description=Run an application on startup
[Service]
Type=simple
ExecStart=/usr/local/bin/your_app_or_script
[Install]
WantedBy=multi-user.target
If networking is a dependency add "After=network.target" in the Unit section. Once you have this file in place add it to startup with:
# Start the app on startup, but will not start it now
systemctl enable yourapp.service
# Start the app now, but doesn't change auto startup
systemctl start yourapp.service
| Note: | See the systemd documentation for in depth documentation on services. |
Backup / Restore
Creating A Production Image
It is usually desired to create a golden image to use for unit production after development is complete. This process can vary greatly from application to application but there are a few steps that are going to be most often wanted. These include cleaning up temporary files, removing files that should be unique and re-generated on the first boot (SSH keys, machine-id files, etc.), setting up the hostname, and so on. We have created a script that will automate most of this process and provides hooks for additional scripts to be called as well. The script is simply passed the device node of the development disk or an existing .dd file. From this, it will create a new .dd file based on the partition scheme with all modifications made to the new image. The image source is left completely untouched and is read only. The script also assumes that the last partition on the disk is the bootable linux partition. If this is not the case or there are multiple partitions that are used in the end application, the script will need to be modified in order to accommodate this fact.
| Note: | The script uses output from various commands. The output format of linux utilities can vary greatly from distribution to distribution, or even within versions of the distribution. It is strongly recommended to verify the final processed image contains everything necessary for the application and that all processes completed without issue. |
The simplest use of the script is:
./prep_customer_image /dev/sdX <output base name>
Note that "/dev/sdX" will need to be changed accordingly. Be sure to pass the whole disk and not just a partition.
The "<output base name>" is used as the base for all files output. For example, if "TechnologicSystems-latest" was used, then the compressed tarball output would be named "TechnologicSystems-latest.tar.bz2" (or it may end with ".tar.xz" depending on the compression used by the script). If no base name is provided, then the current date is used.
Additionally, there are two hooks available in the 'prep_customer_image' script, "prep" and "post". The top of the file has two variables, `PREP_SCRIPTS=""` and `POST_SCRIPTS=""`. Adding in a space separated list of script names to those variables will cause them to be called in order. For example, setting `PREP_SCRIPTS="add_application change_hostname"` will cause the 'prep_customer_image' script to run through its initial steps, then call './add_application', then call './change_hostname', and then will continue with the rest of the script steps.
Every script for "prep" and "post" is called with a single argument, the name of the image file. This specifically will be "<output base name>.dd". At the time of calling the prep scripts, the folder "./mount_point/" will have the last partition of the image file mounted as read/write. It is not wise to modify the image file directly since it is already mounted. All of the post scripts are called after the last partition of the image file is unmounted. This can be useful for creating additional file outputs, extracting specific partition images, etc., from the image itself. We have used these hooks in the past to remove special files and create additional images for our DoubleStore based devices.
It is also possible to run this script directly on the device when booted. This can be used to take an image of eMMC for example, when booted from the SD card. We always recommend doing initial development on SD, creating an image from that on a host PC, and then transferring it to the eMMC. This process makes development and image creation faster. If using the 'prep_customer_image' script from a booted device, be sure there is enough free space as the script creates a disk image of the target disk and then copies that in to a tarball, compressing everything as the final step.
The "prep_customer_image" script can be found in the TS-4100 utilities github.
MicroSD Card
|
Click to download the latest tarball. |
These instructions assume an SD card with one partition. Most SD cards ship this way by default, but if there are modified partitions, a utility such as 'gparted' or 'fdisk' may be needed to remove the existing partition table and recreate it with a single partition.
| Note: | That the partition table must be "MBR" or "msdos", as the "GPT" partition table format is NOT supported by U-Boot. |
Using other OSs
At this time, we're unable to provide assistance with writing SD cards for our products from non-Linux based operating systems. We acknowledge however, that there are methods to write images and files from a variety of difference operating systems. If a native installation of Linux is unavailable, we recommend using a Virtual Machine. See the Getting Started section for links to common virtualization software and Linux installation.
Using a Linux workstation
An SD card can be written to allow it to be bootable. Download the above file and write this from a Linux workstation using the information below. A USB SD adapter can be used to access the card; or if the workstation supports direct connection of SD cards, that can be used instead. Once inserted in to the workstation, it is necessary to discover which /dev/ device corresponds with the inserted SD card before the image can be written.
Option 1: using 'lsblk'
Newer distributions include a utility called 'lsblk' which allows simple identification of the intended card.
| Note: | This command may need to be run as the root user: |
$ lsblk
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sdY 8:0 0 400G 0 disk
├─sdY1 8:1 0 398G 0 part /
├─sdY2 8:2 0 1K 0 part
└─sdY5 8:5 0 2G 0 part [SWAP]
sr0 11:0 1 1024M 0 rom
sdX 8:32 1 3.9G 0 disk
├─sdX1 8:33 1 7.9M 0 part
├─sdX2 8:34 1 2M 0 part
├─sdX3 8:35 1 2M 0 part
└─sdX4 8:36 1 3.8G 0 part
In this case the, SD card is 4GB, so sdX is the target device and already contains 4 partitions. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. Technologic Systems is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!
Option 2: Using 'dmesg'
After plugging in the device, the 'dmesg' command can be used to list recent kernel events. When inserting a USB adapter, the last few lines of 'dmesg' output will be similar to the following (note that this command may need to be run as the root user):
$ dmesg
...
scsi 54:0:0:0: Direct-Access Generic Storage Device 0.00 PQ: 0 ANSI: 2
sd 54:0:0:0: Attached scsi generic sg2 type 0
sd 54:0:0:0: [sdX] 3862528 512-byte logical blocks: (3.97 GB/3.84 GiB)
...
In this case, sdX is shown as a 3.97GB card with a single partition. Note that sdX is not a real device, it could be sda, sdb, mmcblk0, etc. Technologic Systems is not responsible for any damages cause by using the improper device node for imaging an SD card. The instructions below to write to the device will destroy the partition table and any existing data!
Running these commands will write the SD card to our default latest image.
# Verify nothing else has the disk mounted with 'mount'
# If partitions are mounted automatically, they can be unmounted with
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-4100-linux/distributions/debian/ts4100-armhf-stretch-latest.tar.xz
sudo tar -xJf ts4100-armhf-stretch-latest.tar.xz -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. |
After the image is written, the files can all be verified on disk against the original files created in the tarball. Reinsert the disk to verify any block cache is gone, then run the following:
mount /dev/sdX1 /mnt/sd
cd /mnt/sd/
sudo md5sum --quiet -c md5sums.txt
umount /mnt/sd
sync
The 'md5sum' command will report any differences between files and their checksums. Any differences are an indication of failure to write data or a damaged disk.
eMMC
Booted from SD
These instructions assume the TS-4100 is booted from SD card all the way to Linux. They also assume that the eMMC is unmodified, with a single partition. If the partition table has been modified, a utility such as 'gparted' or 'fdisk' may be needed to remove the existing partition table and recreate it with a single partition. Note that the partition table must be "MBR" or "msdos", the "GPT" partition table format is not supported by U-Boot.
# Verify nothing else has the partition mounted
umount /dev/mmcblk1p1
mkfs.ext3 /dev/mmcblk1p1
mount /dev/mmcblk1p1 /mnt/emmc
wget http://ftp.embeddedTS.com/ftp/ts-socket-macrocontrollers/ts-4100-linux/distributions/debian/ts4100-armhf-stretch-latest.tar.xz
tar -xf ts4100-armhf-stretch-latest.tar.xz -C /mnt/emmc
umount /mnt/emmc
sync
| Note: | The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3. |
Once written, the files on disk can be verified to ensure they are the same as the source files in the archive. To do so, run the following commands:
mount /dev/mmcblk1p1 /mnt/emmc
cd /mnt/emmc/
md5sum --quiet -c md5sums.txt
cd -
umount /mnt/emmc
sync
The 'md5sum' command will report any differences between files and their checksums. Any differences are an indication of failure to write data or a damaged disk.
Compile the Kernel
| Note: | This section is incomplete at this time |
Linux 4.9.y (stock)
Compiling the kernel requires an armhf toolchain. We recommend development under Debian Stretch which includes an armhf compiler in the repositories. See the Debian Stretch cross compilation section for instructions on installing a proper cross compiler.
# Install dependencies for kernel build
# The following command is for Ubuntu / Debian workstations. If using a different
# distribution, please consult distribution docs for the proper commands to install
# new packages/tools/libraries/etc.
apt-get install libncurses5-dev bc
# Clone the kernel repository
git clone https://github.com/embeddedTS/linux-lts
# To do a shallow clone of just the latest snapshot of the linux-4.9.y branch, which results in a smaller download size and size on disk, the following command can be used:
# git clone --depth 1 https://github.com/embeddedTS/linux-lts -b linux-4.9.y
cd linux-4.9.y
# Set necessary environment variables for building
export ARCH=arm
export CROSS_COMPILE=arm-linux-gnueabihf-
export LOADADDR=0x80800000
# The following defconfig is the same kernel configuration the unit ships with
make tsimx6ul_defconfig
## Make any changes in "make menuconfig" or driver modifications, then compile
make && make zImage && make modules
To install the kernel and modules to an SD card, attach it to the PC and assuming the the SD card shows up as "/dev/sdX", where "X" is the letter drive corresponding to the SD card.
export DEV=/dev/sdX1
sudo mount "$DEV" /mnt/sd
sudo cp arch/arm/boot/zImage /mnt/sd/boot/zImage
sudo cp arch/arm/boot/dts/imx6ul*ts*.dtb /mnt/sd/boot/
INSTALL_MOD_PATH="/mnt/sd" sudo -E make modules_install
sudo -E make headers_install INSTALL_HDR_PATH="/mnt/sd/usr"
sudo umount /mnt/sd/
sync
| Note: | Shutting down and coming back or operating from another shell instance will require re-exporting the environment variables. |
Linux 5.10.y
| Note: | At this time we do not have an updated userspace more recent than our Debian Stretch distribution. The Debian Stretch disk image can be used as a base and is compatible with the 5.10 kernel. If a newer userspace is needed, we recommend our Buildroot repository for building a complete system image which includes the 5.10 kernel. |
A compatible armhf cross compiler is needed for building the 5.10 kernel. We recommend using the cross compiler available in Debian distributions (the linked instructions are for Debian Stretch but will work on more recent Debian distributions as well). 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
In addition to a cross compiler, a number of host tools are required.
# 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:
git clone -b linux-5.10.y https://github.com/embeddedTS/linux-lts
# Alternatively, a shallow clone can instead be performed to save space on disk. This makes the source smaller and faster to clone, but can make development and updating from remote more complex.
# 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, 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 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 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 tsimx6ul_defconfig
# The minimal defconfig can alternately be used with:
# make tsimx6ul_minimal_defconfig
Build and Install
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
cp arch/arm/boot/dts/*ts*.dtb "${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.
Production Mechanism
| Note: | This section is incomplete at this time |
The TS-4100's U-Boot has the ability to locate and run a U-Boot script file named "/tsinit.scr" on the root of a USB drive. This process occurs when attempting to boot to the U-Boot shell or when booting to USB. If this script exists, U-Boot will load and run it automatically. This is intended for the initial production of units and allows mass programming various media from a USB mass storage device. See the U-Boot USB booting section for information on how this process starts.
The USB blasting image can be downloaded here. This includes a basic linux kernel and a small initramfs that will mount the USB drive at /mnt/usb/ and execute /mnt/usb/blast.sh.
The blast image and scripts require a minimum of 50 MB; this plus any disk images or tarballs used dictate the minimum disk size required. The USB drive must have at least 1 partition, with the first partition being formatted ext2/3 or fat32/vfat.
| Note: | The ext4 filesystem can be used instead of ext3, but it may require additional options. U-Boot does not support the 64bit addressing added as the default behavior in recent revisions of mkfs.ext4. If using e2fsprogs 1.43 or newer, the options "-O ^64bit,^metadata_csum" must be used with ext4 for proper compatibility. Older versions of e2fsprogs do not need these options passed nor are they needed for ext3. |
# This assumes USB drive is /dev/sdc:
sudo mkfs.ext3 /dev/sdc1
sudo mkdir /mnt/usb/
sudo mount /dev/sdc1 /mnt/usb/
sudo tar --numeric-owner -xf /path/to/tsimx6ul_usb_blaster-latest.tar.bz2 -C /mnt/usb/
At this point, disk images or tarballs would be copied to the /mnt/usb/ folder and named as noted below. The latest disk images we provide can be downloaded from our FTP site, see the backup and restore section for links to these files. Note that the script expects images and tarballs to have specific names. When using an ext* filesystem, symlinks can be used.
The formatted USB drive boots into a small Buildroot initramfs environment with filesystem and partitioning tools installed. This can be used to format SD, eMMC, or other disks. The Buildroot environment starts up and calls /blast.sh on the USB device. By default this script is set up to look for a number of of specific files on the USB disk and write these to media on the host device. Upon completion of the script the green or red LEDs will blink to visually indicate a pass or fail of the script. This script can be used without modification to write images from USB with these filenames:
| SD Card | sdimage.tar.{bz2,xz} | Tar of the filesystem. This will repartition the SD card to 1 ext4 partition and extract this tar to the filesystem. If present, a /md5sums.txt file will be checked and every file can be verified on the filesystem. This md5sums file is optional and can be omitted, but it must not be blank if present. |
|---|---|---|
| sdimage.dd.{bz2,xz} | Disk image of the card. This will be written to the SD card block device directly. If present, a sdimage.dd.md5 file be used to verify the data written to the SD card against this checksum. | |
| eMMC | emmcimage.tar.{bz2,xz} | Tar of the filesystem. This will repartition the eMMC to 1 ext4 partition and extract this tar to the filesystem. If present, a /md5sums.txt file will be checked and every file can be verified on the filesystem. This md5sums file is optional and can be omitted, but it must not be blank if present. |
| emmcimage.dd.{bz2,xz} | Disk image of the card. This will be written to mmcblk1 directly. If present, a emmcimage.dd.md5 file be used to verify the data written to the SD card against this checksum. |
Most users should be able to use the above script without modification. Our buildroot sources are available from our github repo. To build the whole setup and create a USB drive, the following commands can be used. See the repository README for information on the project and how to make modifications.
make tsimx6ul_usbprod_defconfig && make
The resulting output file tsimx6ul-usb-production-rootfs.tar.bz2 can be unpacked to the first partition of the USB drive as outlined above.
TS-8820-4100 MUXBUS Interface
The TS-4100 uses the MUXBUS protocol to read and write the TS-8820 FPGA registers. The TS-4100 FPGA does not natively support the MUXBUS protocol in any way, however all of the relevant connection pins are accessible to the TS-4100 FPGA as GPIO pins. In order to facilitate the communication, the TS-4100 ZPU is loaded with a program that is designed to accept data from the CPU and perform MUXBUS bus cycles by directly manipulating the FPGA GPIO pins.
Loading the MUXBUS Application
The utility 'tszpuctl' is used to compile applications, load them in to the ZPU, perform ZPU reset, dump ZPU RAM, and get basic information about the ZPU itself. The sources for 'tszpuctl' as well as the "zpu_muxbus" application are available from the ts4100-utils github repository.
The ZPU can be loaded with the MUXBUS application with the following commands:
tszpuctl -l /usr/local/bin/zpu/zpu_muxbus.bin
Note that the ZPU must be re-loaded with this application each time the unit is booted up. The program is loaded directly in to ZPU RAM and executed from there. It is also possible to compile the "zpu_muxbus.c" file to a .bin file and pass that to 'tszpuctl' for faster loading.
Using the ts8820ctl Application
With the ZPU loaded, it is now ready to accept commands to read and write TS-8820 FPGA registers. Many of the TS-8820 features listed below show an example of using "ts8820ctl" to interact with I/O or other peripherals. The 'ts8820ctl' application is included in the stock TS-4100 image and requires the ZPU be loaded with the "zpu_muxbus" application first. If the ZPU is not loaded, 'ts8820ctl' will return with an error indicating that it was unable to communicate with the ZPU.
Custom Applications
The 'ts8820ctl' application is meant as a demo application. While it can be used on its own it may be necessary to integrate its features in to a larger application. This is the reason that 'ts8820ctl' is broken down in to multiple layers.
The top level "src/ts8820ctl.c" file in the ts4100-utils github repository is the commandline interface. From there it makes a number of calls to functions provided by "src/ts8820.c". These functions do the heavy lifting of formatting data and making calls to the ZPU via a custom FIFO interface. The functions in "ts8820.c" can be called from other applications to directly manipulate the TS-8820 peripherals.
Features
FPGA
The TS-8820 is powered by a Lattice XP2 FPGA with 5000 LUTs. Many of the features of the TS-8820 are driven by logic in this FPGA. The CoM attached to the TS-8820 will likely also have an FPGA, but all mentions of an FPGA in this document reference the FPGA on the TS-8820 itself.
The CoM communicates with the TS-8820 FPGA using the MUXBUS, a simple address/data bus defined by Technologic Systems. Application developers do not need to understand the hardware layers involved to read/write the TS-8820 register map. See the demo application source, ts8820ctl.c, for more information on the software interface for the TS-8820.
For applications that require custom logic or interfaces please contact us regarding FPGA customization.
Battery Socket
The coin cell battery is not required for normal TS-8820 operation. The battery provides backup power for the battery backed SRAM and for the real time clock located on the SoM. Without a battery, however, a loss of power will result in a loss of RTC time in the SoM and SRAM data on the TS-8820.
Digital Outputs
The TS-8820 offers 6 digital outputs. OUT1 through OUT4 are isolated and act as a solid state relay capable of switching up to 40 VDC at 1 A continuous draw. OUT5 and OUT6 are non-isolated, able to sink up to 1 A continuous current, and are 40 VDC tolerant.
The outputs can be controlled directly through the 'ts8820ctl' application. See "ts8820ctl.c" and "ts8820.c" for examples of how this writes to the TS-8820 registers.
With the 'ts8820ctl' application, all 6 outputs are manipulated in a single command. That is, a 6-bit value is passed as an argument, and that value is directly set to the outputs. For example, to set OUT5:
ts8820ctl --setdio=0x10
When an output is activated its associated LED indicator is enabled to provide visual feedback.
Isolated Outputs
Digital outputs OUT1 through OUT4 are isolated, each having their own positive and negative terminal. Each isolated output acts as a solid state relay allowing current to flow through the contacts only when it is activated. The isolated outputs are able to switch up to 40 VDC at 1 A continuous current draw. Isolated output terminals are made available on the P7 terminal block.
Non-Isolated Outputs
Digital outputs OUT5 and OUT6 are non-isolated, they rely on the main TS-8820 ground and only have a single contact. Each non-isolated output is a low side switch capable of sinking current when activated. The non-isolated outputs are capable of sinking 1 A continuous current with 40 V input voltage. Non-isolated input terminals appear on the P2 terminal block.
PWM
The TS-8820 has 6 PWM outputs. PWM channels 1 to 6 feed digital outputs 1 to 6 respectively when the PWM override bit is set for a given output.
For all 8 PWM channels, the PWM frequency is approximately (12207/(2^prescaler)) Hz, where the prescaler value is 3 bits wide. That is, a prescaler value of 0 through 7. The PWM duty cycle has 12 bits of resolution. If bit 12 of a PWM register is set, then the PWM output for that channel will be 100% high. Otherwise, the duty cycle setting is divided by 4096 to give the effective duty cycle.
To give OUT5 a ~3 kHZ 50% duty cycle PWM output using ts8820ctl, the following arguments would be used:
# -P sets the PWM frequency via a prescaler value to (12207/(2^VALUE))Hz.
# --mvolts= sets the PWM duty cycle percentage from a decimal scale of 0-10000
# --pwm= PWM channel to enable and modify
ts8820ctl --pwm=5 --mvolts=5000 -P 2
Digital Inputs
The TS-8820 offers 14 digital input pins. There are 8 isolated inputs that are 30 V tolerant. The 6 non-isolated inputs are 40 V tolerant.
The inputs can be polled directly through the ts8820ctl application. See ts8820ctl.c and ts8820.c for examples of how this reads from the TS-8820 registers.
With the ts8820ctl application, all 14 inputs can be read with a single command. A 14-bit value is returned in hex in a format that can be parsed easily by scripting languages. For example, the following output indicates that IN1 and IN3 are active:
ts8820ctl --getdio
dio=0x5
When an input is activated its associated LED indicator is enabled to provide visual feedback.
Isolated Inputs
Digital inputs IN1 though IN8 are isolated, each having their own positive and negative terminal. In order to activate an input, a potential of at least 1.4 VDC and not more than 30 VDC must be generated across these terminals. Isolated input terminals are located on P1 and P7 terminal blocks.
Buffered Inputs
Digital inputs IN9 through IN14 are non-isolated, buffered, active low inputs. Each pin has a nominal threshold of 2.5 VDC, a 3.24 Kohm pull-up to 5 VDC, and are 40 VDC tolerant. Non-isolated inputs are located on the P2 terminal block.
Pulse Counter
Each of the 14 digital inputs has an associated 16-bit pulse counter. The counters are reset at power on, and continue counting through their entire 16 bit range before rolling over. There is no mechanism to clear the counters arbitrarily.
Each counter is incremented once per transition of the associated IN channel, on the asserted edge of the signal. IN1-IN8 counters increase when a positive voltage is applied while IN9-IN14 counters increment when the pin is grounded. The pulse counters do not increment when the signal is returning to its deasserted state.
| Note: | The counter logic does not include any debounce; care should be taken when using the pulse counter for a mechanical contact closure to ensure an accurate count. |
The current count for any given channel can be acquired with:
ts8820ctl --counter <in>
ts8820ctl --counter 10
# Returns the output of
counter10=4
ADC Channels
The TS-8820 offers 16 channels of single ended bi-polar ADC inputs. These ADC inputs are provided by two separate 8 channel ADC devices. Each ADC controller supports a selectable voltage (via GPIO from the SoM, see below) ranges of -5 V to +5 V as well as -10 V to +10 V. This means that each set of 8 channels can be set to different ranges. Each set of 8 channels are sampled simultaneously inside the ADC device.
All 16 ADC inputs are located on the P3, P4, and P5 terminal blocks. While each ADC has a pair of inputs, they are single ended ADC channels; all negative input terminals connect to the TS-8820 common ground.
Additionally, the ADC devices support a number of oversampling options, also controlled via GPIO from the SoM. Enabling oversampling has the effect of adding a digital filter function after the ADC. Increasing the oversampling ratio will decrease the effective sampling rate of the ADC but will increase the signal to noise ratio of each channel. The oversampling rate is shared between both ADC devices, that is, the rate can not be independently set per-device.
Setting the ADC voltage range:
| DIO | Val | Range |
|---|---|---|
| CN2_56 | 1 | -10 V to +10 V |
| CN2_56 | 0 | -5 V to +5 V |
| DIO | Val | Range |
|---|---|---|
| CN2_58 | 1 | -10 V to +10 V |
| CN2_58 | 0 | -5 V to +5 V |
Setting the oversampling rate:
| CN2_64 | CN2_62 | CN2_60 | OS Rate |
|---|---|---|---|
| 0 | 0 | 0 | N/A |
| 0 | 0 | 1 | 2 |
| 0 | 1 | 0 | 4 |
| 0 | 1 | 1 | 8 |
| 1 | 0 | 0 | 16 |
| 1 | 0 | 1 | 32 |
| 1 | 1 | 0 | 64 |
| 1 | 1 | 1 | Invalid |
| Note: | SoM GPIO pins will usually start as inputs with pull up resistors. Therefore the default range will likely be -10 V to +10 V with an invalid oversampling rate. It is advised to set up these pins before acquiring ADC samples. |
Current Loops (4-20 mA measurement)
All 16 ADC channels independently support 4-20 mA current loop measurements. This is achieved by setting a pin jumper for the respective channel on the current loop enable pin header. Setting a jumper will electrically enable a 220 Ω 0.5% resistor from the ADC channel to ground allowing for a constant current measurement.
Thermistor
The TS-8820 supports up to 8 thermistors on channels 1 though 8. Support for a thermistor is enabled via software, the ADC pullup bit of TS-8820 FPGA register 0x2. Setting bit 8 enables a pull up on ADC channels 1 and 2, setting bit 9 enables a pull up on ADC channels 3 and 4, and setting bit 10 enables a pull up on channels 5 through 8. When enabled, each channel will get a separate 6.04 kΩ resistor to +12.5 V allowing the use of a thermistor probe.
ADC Usage
The 'ts8820ctl' application can be used to quickly sample the ADCs. This will send simultaneous sampling commands to each of the two ADC devices which will then sample all 16 channels in total the amount of times specified. See the "ts8820ctl.c" and "ts8820.c" files for examples on how this operation takes place.
For example, to sample all of the channels 5 times, the following command would be used:
ts8820ctl --sample=5
Collected 80 samples total.
Ch 1 Ch 2 Ch 3 Ch 4 Ch 5 Ch 6 Ch 7 Ch 8 Ch 9 Ch10 Ch11 Ch12 Ch13 Ch14 Ch15 Ch16
---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
-7626 2195 2193 2199 2192 2195 2195 2192 2189 2189 2193 2190 2189 2192 2191 2191
-7626 2194 2192 2198 2191 2194 2194 2191 2188 2189 2192 2189 2188 2191 2189 2190
-7626 2193 2191 2197 2190 2193 2193 2190 2187 2188 2191 2188 2186 2190 2189 2189
-7626 2189 2188 2193 2186 2189 2190 2186 2183 2184 2187 2184 2183 2186 2185 2185
-7626 2189 2187 2192 2186 2188 2189 2186 2183 2183 2187 2184 2182 2185 2184 2185
Above, channel 1 has a -7.62 V voltage source attached to it, all other channels are left unconnected. The range is set at -10 V to +10 V, and the oversampling rate is set to 64.
Note that on the TS-4100, the range defaults to -5 V to +5 V and oversampling is in the "invalid" state due to how the GPIO pins are set up in the CPU.
Before the above measurement was taken, the following commands were run on the TS-4100 in order to set the correct range and oversampling rate:
echo 120 > /sys/class/gpio/export
echo 121 > /sys/class/gpio/export
echo 122 > /sys/class/gpio/export
echo low > /sys/class/gpio/gpio120/direction
echo high > /sys/class/gpio/gpio121/direction
echo high > /sys/class/gpio/gpio122/direction
echo 119 > /sys/class/gpio/export
echo 118 > /sys/class/gpio/export
echo high > /sys/class/gpio/gpio118/direction
echo high > /sys/class/gpio/gpio119/direction
These GPIO states must be set each time the unit is powered up.
DAC Channels
The TS-8820 has 4 channels of 0 to +10 V DAC outputs. Each DAC channel has a positive and negative terminal connection. The negative side of the terminals are connected to the common ground of the TS-8820 and are non-isolated. The DAC terminals are on the P3 and P9 terminal blocks.
The DAC channels each have 12 bits of resolution that correspond to 0 to +10 V output. The upper bit (bit 15) of each register is a control bit that is used to synchronize the output of all 4 DAC channels. This means that all four registers can be updated without modifying the actual DAC output. Setting the control bit of any DAC channel register will case an update of the DAC output of all four channels. If the DAC register has not been modified, the update will still be sent but the actual output will remain the same. Reading this control bit will indicate if the synchronization is complete. Writing the DAC registers while the control bit is still asserted, indicating busy, will result in undefined behavior. The update process from setting the control bit to its completion takes approximately 3 microseconds.
When 0 is written to the control bit, the DAC values are updated internally in the FPGA but not transferred to the DAC. Thus any set of channels can be updated simultaneously by only writing a one on the final write.
The DAC channels can be controlled through 'ts8820ctl'. Note that the "--setdac" option to 'ts8820ctl' will always set the control bit of the selected register. See "ts8820ctl.c" and "ts8820.c" for an example of how this process works.
The following command would set DAC output 1 to 0.5 V:
ts8820ctl --setdac=1 --mvolts=500
Isolated CAN Port
The TS-8820 provides an isolated CAN port on the P10 terminal block. The CAN interface itself is from the SoM with the TS-8820 facilitating the isolated physical interface.
Optionally, a 124 ohm termination resistor can be electrically added by setting the Term. CAN jumper.
More information about the CAN interface is available in the TS-4100 manual.
Isolated RS-232
The TS-8820 provides a single isolated RS-232 port on the P10 terminal block. The UART interface itself is from the SoM with the TS-8820 facilitating the isolated RS-232 physical interface.
By default, this UART port is connected to the ttymxc1 device on the TS-4100.
Isolated RS-485
The TS-8820 provides a single isolated RS-485 port on the P10 terminal block. The UART interface itself is from the SoM with the TS-8820 facilitating the isolated RS-485 physical interface.
Optionally, a 124 ohm termination resistor can be electrically added by setting the Term. 485 jumper.
By default, this port is connected to the ttymxc3 on the TS-4100. The TS-4100 uses an automatic TXEN for half-duplex RS-485 handled by a CPU GPIO pin. However in order for this to function, it is necessary to modify the TS-4100 FPGA crossbar mux to route this CPU GPIO pin to the TXEN pin on the TS-8820. The following command needs to be run each time the unit is powered on in order for RS-485 to properly function:
tshwctl --addr 177 --poke 2
This connects the CPU GPIO pin directly to the RS-485 TXEN pin on the TS-8820 via internal switches in the TS-4100 FPGA.
Relays
The TS-8820 provides 4 mechanical SPDT relays. Each relay has a common connection, a normally open (NO), and normally closed (NC) contact. All 4 sets of contacts are located on the P8 terminal block.
Each relay has contacts rated for 277 VAC / 30 VDC @ 5 A (NO contacts) and 3 A (NC contacts). The use of these relays in the TS-8820 are rated for 30 VAC / 30 VDC @ 5 A (NO) and 3 A (NC).
These 4 relays are manipulated by GPIO from the SoM, not the TS-8820 itself. The relays are controlled by the following GPIO pins:
See the TS-4100 GPIO manual for information on how to manipulate the GPIO for the relays.
Power Supply
The TS-8820 can be powered via PoE or direct DC voltage input to the terminal block connectors. If PoE is not used, power must be supplied on terminal block P6.
DC via Terminal Blocks
Direct power input can be applied to the P6 terminal block. There are three terminals for power and three for a ground connection. Each of the three sets of terminals are electrically connected together internally in the TS-8820. Operational range of the TS-8820 is +10 VDC to +30 VDC on these inputs. Supply an external ground on terminal 10, 11, and/or 12. Supply +10 V to +30 V on terminal 7, 8, and/or 9.
802.3af PoE
The TS-8820 is IEEE 802.3af PoE compliant. This allows the whole unit to be powered directly from a PoE sourcing device.
When powered via PoE, +24 VDC is made available on the P6 terminal block power terminals. Ensure that the total power draw of the system does not exceed the limits defined by IEEE 802.3af and that power is not also supplied to the TS-8820 on these pins!
LEDs
The TS-8820 has 27 LEDs used to indicate the electrical status of the inputs and outputs on the device. LEDs are labelled as "LED#" on the PCB silkscreen.
The majority of the LEDs are not able to be directly controlled, they turn on or off as a reaction to the status of the I/O they are connected to. For example, when DIG_OUT1 is set, LED17 will turn on. The "System" LEDs are the exception to this and are controlled via the SoM LED interface.
| LED | FUNCTION | --- | LED | FUNCTION |
|---|---|---|---|---|
| 1 | System RED_LED | 2 | Doesn't exist. | |
| 3 | System Power | 4 | System GREEN_LED | |
| 5 | RELAY_1 | 6 | RELAY_2 | |
| 7 | RELAY_3 | 8 | RELAY_4 | |
| 9 | DIG_IN1 | 10 | DIG_IN2 | |
| 11 | DIG_IN3 | 12 | DIG_IN4 | |
| 13 | DIG_IN5 | 14 | DIG_IN6 | |
| 15 | DIG_IN7 | 16 | DIG_IN8 | |
| 17 | DIG_OUT1 | 18 | DIG_OUT2 | |
| 19 | DIG_OUT3 | 20 | DIG_OUT4 | |
| 21 | DIG_IN9 | 22 | DIG_IN10 | |
| 23 | DIG_IN11 | 24 | DIG_IN12 | |
| 25 | DIG_IN13 | 26 | DIG_IN14 | |
| 27 | DIG_OUT5 | 28 | DIG_OUT6 |
External Interfaces
Terminal Blocks
| Note: | If you have a REV A board disregard the P1-P10 labeling as printed on the PCB. |
|
|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Ethernet Connector
The TS-8820 can connect to any Ethernet LAN. The Ethernet connector includes LEDs indicating link and activity. The link LED should be on whenever the TS-8820 is powered and connected to a LAN. This connector allows the TS-8820 to be powered by PoE.
USB Host
The USB is available on two ports as a USB 2.0 host.
 |
|
DB9 Connector
|
|
Register Map
Most of the access to the I/O is abstracted by 'ts8820ctl' and "ts8820.c", but it is also possible to access them directly through MUXBUS registers if applicable.
| Offset | Bits | Description |
|---|---|---|
| 0x0 | 15:0 | Model ID: Reads 0x8820 |
| 0x2 | 15:11 | Reserved |
| 10 | Pull-up 5-8 enable | |
| 9 | Pull-up 3-4 enable | |
| 8 | Pull-up 1-2 enable | |
| 7 | H-bridge 2 enable (contacts go high-Z otherwise) | |
| 6 | H-bridge 1 enable (contacts go high-Z otherwise) | |
| 5 | H-bridge 2 direction | |
| 4 | H-bridge 1 direction | |
| 3:0 | FPGA Revision | |
| 0x4 | 15:14 | Reserved |
| 13:0 | Digital inputs 14:1 | |
| 0x6 | 15:10 | Reserved |
| 9:0 | SRAM Page register | |
| 0x8 | 15:12 | Reserved |
| 11:6 | Override Digital Outputs 6:1 with PWM | |
| 5:0 | Digital Output Values 6:1 | |
| 0xa | 15:0 | Reserved |
| 0xc | 15:0 | Reserved |
| 0xe | 15:0 | Reserved |
| 0x10 | 15:13 | PWM #1 Prescaler |
| 12:0 | PWM #1 Duty Cycle | |
| 0x12 | 15:13 | PWM #2 Prescalar |
| 12:0 | PWM #2 Duty Cycle | |
| 0x14 | 15:13 | PWM #3 Prescaler |
| 12:0 | PWM #3 Duty Cycle | |
| 0x16 | 15:13 | PWM #4 Prescaler |
| 12:0 | PWM #4 Duty Cycle | |
| 0x18 | 15:13 | PWM #5 Prescaler |
| 12:0 | PWM #5 Duty Cycle | |
| 0x1a | 15:13 | PWM #6 Prescaler |
| 12:0 | PWM #6 Duty Cycle | |
| 0x1c | 15:13 | PWM #7 Prescaler (H Bridge 1) |
| 12:0 | PWM #7 Duty Cycle (H Bridge 1) | |
| 0x1e | 15:13 | PWM #8 Prescaler (H Bridge 2) |
| 12:0 | PWM #8 Duty Cycle (H Bridge 2) | |
| 0x20 | 15:0 | Pulse Counter #1 (RO) |
| 0x22 | 15:0 | Pulse Counter #2 (RO) |
| 0x24 | 15:0 | Pulse Counter #3 (RO) |
| 0x26 | 15:0 | Pulse Counter #4 (RO) |
| 0x28 | 15:0 | Pulse Counter #5 (RO) |
| 0x2a | 15:0 | Pulse Counter #6 (RO) |
| 0x2c | 15:0 | Pulse Counter #7 (RO) |
| 0x2e | 15:0 | Pulse Counter #8 (RO) |
| 0x30 | 15:0 | Pulse Counter #9 (RO) |
| 0x32 | 15:0 | Pulse Counter #10 (RO) |
| 0x34 | 15:0 | Pulse Counter #11 (RO) |
| 0x36 | 15:0 | Pulse Counter #12 (RO) |
| 0x38 | 15:0 | Pulse Counter #13 (RO) |
| 0x3a | 15:0 | Pulse Counter #14 (RO) |
| 0x3c | 15:0 | Reserved |
| 0x3e | 15:0 | Reserved |
| 0x80 | 15:0 | ADC Core ID (reads 0xadc1) |
| 0x82 | 15:8 | ADC Channel Mask (0 = do not save channel data) |
| 7:6 | Highest number chip to use (0-3, if 01 then sample chip 0 and chip 1) | |
| 5 | 1 = Force standby | |
| 4 | 1 = Use standby between samples to save power | |
| 3 | 1 = Smart DMA IRQ mode | |
| 2 | 1 = Enable IRQ | |
| 1 | 1 = Collect samples, 0 = stop | |
| 0 | 1 = Reset ADC chips and all FIFOs | |
| 0x84 | 15 | 1 = There has been a FIFO overflow since last reset |
| 14:0 | Number of samples available to be read | |
| 0x86 | 15:0 | Sample Data (RO) |
| 0x88 | 15:0 | Sampling period LSB (RW) |
| 0x8a | 15:0 | Sampling period MSB (RW) |
| 0x8c | 15:0 | IRQ Threshold (RW) |
| 0x8e | 15:0 | Reserved |
| 0x90 | 15:0 | Reserved |
| 0x92 | 15:0 | Reserved |
| 0x94 | 15:0 | Reserved |
| 0x96 | 15:0 | Reserved |
| 0x98 | 15:0 | Reserved |
| 0x9a | 15:0 | Reserved |
| 0x9c | 15:0 | Reserved |
| 0x9e | 15:0 | Reserved |
| 0xa0 | 15:0 | DAC 1 Control Register |
| 0xa2 | 15:0 | DAC 2 Control Register |
| 0xa4 | 15:0 | DAC 3 Control Register |
| 0xa6 | 15:0 | DAC 4 Control Register |
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.