Debian Linux 9 (Stretch)
Debian Stretch(9)
Getting Started
We've created an aftermarket image that runs Linux kernel 4.9 and offers a Debian Stretch userspace environment. The latest tarball of this can be downloaded below:
This can then be written to a microSD card or the on-board eMMC flash in order to be booted on the TS-7553-V2.
Debian Networking
By default, Debian Stretch does not configure any interfaces to be brought up or configured.
Debian can automatically set up the networking based on the contents of "/etc/network/interfaces.d/" files. For example, to enable DHCP for "eth0" by default on startup:
echo "auto eth0
iface eth0 inet dhcp" > /etc/network/interfaces.d/eth0
To set up a static IP:
echo "auto eth0
iface eth0 inet static
address 192.168.0.50
netmask 255.255.255.0
gateway 192.168.0.1" > /etc/network/interfaces.d/eth0
echo "nameserver 1.1.1.1" > /etc/resolv.conf
To make this take effect immediately for either option:
service networking restart
To configure other interfaces, replace "eth0" with the other network device name. Some interfaces may use predictable interface names. For example, the traditional name for an ethernet port might be "eth1", but some devices may use "enp1s0" for PCIe, or "enx00D069C0FFEE" (the MAC address appended) for USB ethernet interfaces. Run 'ifconfig -a' or 'ip a' to get a complete list of interfaces, including the ones that are not configured.
Debian Wi-Fi Client
Wireless interfaces are also managed with configuration files in /etc/network/interfaces.d/. For example, to connect as a client to a WPA network with DHCP. Note some or all of this software may already be installed on the target.
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 with the contents:
allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-ssid youressid
wpa-psk 151790fab3bf3a1751a269618491b54984e192aa19319fc667397d45ec8dee5b
To have this take effect immediately:
service networking restart
For more information on configuring Wi-Fi, see Debian's guide here.
Debian Wi-Fi Access Point
This section will discuss setting up the WiFi device as an access point that is bridged to an ethernet port. That is, clients can connect to the AP and will be connected to the ethernet network through this network bridge. The ethernet network must provide a DHCP server; this will be passed through the bridge to WiFi client devices as they connect.
It is also possible to run a DHCP client on the platform itself. In this case the hostapd.conf file needs to be set up without bridging and a DHCP server needs to be configured. Refer to Debian's documentation for more details on DHCP server configuration.
The 'hostapd' utility is used to manage the access point of the device. This is usually installed by default, but can be installed with:
apt-get update && apt-get install hostapd -y
| Note: | The install process may start an unconfigured 'hostapd' process. This process must be killed before moving forward. |
Modify the file "/etc/hostapd/hostapd.conf" to have the following lines:
ssid=YourWiFiName
wpa_passphrase=Somepassphrase
interface=wlan0
channel=7
driver=nl80211
logger_stdout=-1
logger_stdout_level=2
wpa=2
wpa_key_mgmt=WPA-PSK
| 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, modify the hostapd configuration to understand the bridge interface:
echo "bridge=br0" >> /etc/hostapd/hostapd.conf
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
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 mode. This is usually installed by default, but can separately 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
logger_stdout=-1
logger_stdout_level=2
wpa=2
wpa_key_mgmt=WPA-PSK
| 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 virtual 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.
Cellular Data Network
DC-TS767-MT MultiTech Modem
The TS-7553-V2 includes support for the Multitech MTSMC-G2 or MTSMC-H5 connected via the TS-DC767-MT daughter card, which can connect to the internet using pppd. The modem is attached to the HD1 Header, also called the Daughter Card interface. The modem itself can be configured with the following commands:
ln -s /dev/ttymxc6 /dev/ttymultidc
There are two GPIO pins that can control reset and RTS of the cell modem. These two pins default to an I2C mode, so before they can be used, they must have the pinmux set to GPIO. This can be done with the following two commands:
peekpoke 32 0x20e0118 0x5 #Set RTS pin to GPIO, GPIO 69
peekpoke 32 0x20e011c 0x5 #Set reset pin to GPIO, GPIO 70
The DIO pins can be controlled now from the linux GPIO subsystem. In order to function properly, the RTS pin must be low, and the reset must be high. This can be done with the following commands:
echo "69" > /sys/class/gpio/export
echo "70" > /sys/class/gpio/export
echo "low" > /sys/class/gpio/gpio69/direction
echo "high" > /sys/class/gpio/gpio70/direction
The pppd application must be installed and any required modules loaded:
apt-get update && apt-get install -y ppp
This example is configured for T-Mobile in the US:
/etc/ppp/peers/tmobile
/dev/ttymultidc noauth 115200 debug usepeerdns persist defaultroute connect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile" disconnect "/usr/sbin/chat -v -f /etc/ppp/chatscripts/tmobile-disconnect"
/etc/ppp/chatscripts/tmobile
TIMEOUT 10 ABORT 'BUSY' ABORT 'NO ANSWER' ABORT 'ERROR' "" "\p\p\p\p\p\p\p\p\p\p\p\p+++\p\p\p\p\p\p\p\p\p\p\p\p" "" "ATH0" "OK" 'AT+CGDCONT=1,"IP","wap.voicestream.com"' ABORT 'NO CARRIER' OK 'ATD*99***1#' CONNECT
/etc/ppp/chatscripts/tmobile-disconnect
"" "\K" "" "+++ATH0"
Using a different carrier you will likely only need to replace wap.voicestream.com with the access point for your carrier.
To start pppd:
pppd call tmobile
# Or for more logging information:
# pppd nodetach call tmobile
This will create a ppp0 interface that can now be used as a standard network interface, and should set up a default route to the internet. For other carriers, typically you will only need a different access point listed in the AT+CGDCONT call, but further adjustments may be necessary.
| Note: | We have observed that the MTSMC-H5 connected to some networks has issues at or below 115200 baud. The issues observed are connection timeouts with the network itself. The connection between the modem and host device remain rock solid. While many applications are tolerant to the connection being reset, we have found some network downloads will abort without being able to recover. Running the unit at a faster baud rate, 230400 or higher, has been observed to eliminate this issue entirely. This does mean, however, that every time the device is started up, the modem must be issued an AT+IPR command (as noted below) at 115200 baud, then pppd started with the matched and higher baud rate in the peer script as shown above. |
Faster Data Rates
While the MTSMC-G2 (GPRS) is limited to 115200 baud, the MTSMC-H5 (HDSPA) can communicate over serial up to 921600 allowing actual transfer rates around 80-90KB/s.
To set a custom baudrate in Linux, the method depends on the CPU and kernel support. More recent UART peripherals have a higher clock and a smarter driver, and can therefore use custom baud rates inherently. However, some systems require the use of 'setserial' using the spd_cust flag and some manual settings. When the spd_cust baud rate is set, Linux will re-purpose 38400 baud to use the set custom baud rate.
First, test the unit to see if it is possible to open up the UART with a higher baud rate:
picocom -b 921600 /dev/ttymultidc
If the higher baud is unsupported, picocom will return a failure similar to the following:
FATAL: failed to add device /dev/ttymultidc: Invalid baud rate
If the above error is received, then the method below using setserial must be used.
Otherwise, the port can be closed, re-opened at 115200 baud to communicate with the modem, and then the following command can be used to tell the cell modem to enter a higher baud rate:
AT+IPR=921600
Now the port can be closed everything will function at the higher baud rate. Be sure to update the providers file. Using the example T-Mobile configuration, edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).
| Divisor | Rate |
|---|---|
| 1 | 921600 |
| 2 | 460800 |
| 3 | 307200 |
| 4 | 230400 |
| 5 | 184320 |
| 6 | 153600 |
| 7 | 131657 |
| 8 | 115200 |
Larger divisors will also work, but this should cover the common range. Using the setserial command you can specify the divisor. For example, to reach 115200 with the alternative baud base:
setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 8
Next you will need to tell the modem to communicate at the faster baud rates. You can use a client like picocom or minicom to connect directly to the modem to send it commands.
picocom -b 38400 /dev/ttymultidc
Even though we are talking at 115200, 38400 must be specified since we are using a custom baud_base. You can test communication with the modem again by typing "AT", pressing enter, and receiving "OK". To reconfigure the modem to the faster 921600 baud rate you can send it this command:
AT+IPR=921600
This will respond with OK, but now you will need to quit out of picocom (ctrl a,x) and reconfigure the baud base to use divisor 1:
setserial /dev/ttymultidc spd_cust baud_base 921600 divisor 1
The only change now needed is in your providers file. Using the example T-Mobile configuration , edit /etc/ppp/peers/tmobile and change 115200 to 38400. Starting pppd will now allow communication around 80-90KB/s (depending on your local cell tower's availability).
Troubleshooting
If you are not able to obtain a ppp connection there are a few values you can check:
Troubleshooting: Cell Signal
Make sure ppp is not running, and execute these commands to check the signal strength.
stty raw -echo speed 115200 -F /dev/ttymultidc
cat /dev/ttymultidc &
echo -e "AT+CSQ\r\n" > /dev/ttymultidc
killall cat
The return value should be something like "+CSQ: 9,2", or with no connection, +CSQ: 99,99. The second argument is the signal strengh which follows this table:
| 0 | -113 dBm or less |
| 1 | -111 dBm |
| 2 to 30 | -109 to -53dBm |
| 31 | -51dBm or greater |
| 99 | not known or detectable |
If you return 99, make sure the antenna is connected and that you are in an area with good signal from your provider. Even without a valid SIM card you can have a good connection. If you are in another country, you may need to adjust the band for those supported by your carrier. The default value is appropriate for most US based carriers. Refer to the +WMBS command in your AT command guide for more options.
Troubleshooting: SIM card
If you have a good signal strength but are not obtaining a connection you can verify that the modem is able to read the subscriber number. This proves your SIM card is valid.
stty raw -echo speed 115200 -F /dev/ttymultidc
cat /dev/ttymultidc &
echo -e "AT+CNUM\r\n" > /dev/ttymultidc
killall cat
With a valid SIM this will return something like:
+CNUM: "","12345678901",129
If the SIM not detected you will only read ERROR. Make sure in this case that the card is inserted in the right direction so the pads on the card line up with the socket.
Troubleshooting: Other Options
If neither of the above steps get you connected you may want to contact your service provider for more information about where your connection attempts are failing.
NimbeLink Skywire modem
The CN5 XBee Socket is able to support NimbeLink Skywire Embedded modems. Information on setting up and configuring the power and USB interface for Skywire modules can be found here. Please note that there are various models of the Skywire modules that all support different interfaces. These include cdc_ether, cdc_ncm, USB serial, and a simple TTL UART. Both the USB ethernet and NCM interfaces present a network device to the system, while the USB serial and UART interfaces require PPP to manage the connection.
Please see the NimbeLink documentation for the specific module in use for more detailed information on establishing connection with a cellular network via the modem.
| Note: | Modems using the QBG95 hardware are not compatible with the TS-7553-V2 due to hardware incompatibility. This incompatibility is only on the TS-7553-V2 and QBG95. That is, other modems do not have this issue with the TS-7553-V2, and our other platforms are compatible with the QBG95 modem. |
Debian Application Development
Debian Stretch Cross Compiling
Debian Stretch provides cross compilers from the Debian apt repository archive for Debian Stretch. An install on a workstation can build for the same release on other architectures. A Linux desktop or laptop PC, virtual machine, or chroot will need to be used for this. Debian Stretch for a workstation can be downloaded from here.
From a Debian workstation (not the target), run these commands to set up the cross compiler:
# Run "lsb_release -a" and verify Debian 9.X is returned. These instructions are not
# expected to work on any other version or distribution.
su root
# Not needed for the immediate apt-get install, but used
# so we can install package:armhf for cross compiling
dpkg --add-architecture armhf
apt-get update
apt-get install curl build-essential crossbuild-essential-armhf -y
This will install a toolchain that can be used with the prefix "arm-linux-gnueabihf-". The standard GCC tools will start with that name, eg "arm-linux-gnueabihf-gcc".
The toolchain can now compile a simple hello world application. Create hello-world.c on the Debian workstation:
#include <stdio.h>
int main(){
printf("Hello World\n");
}
To compile this:
arm-linux-gnueabihf-gcc hello-world.c -o hello-world
file hello-world
This will return that the binary created is for ARM. Copy this to the target platform to run it there.
Debian Stretch supports multiarch which can install packages designed for other architectures. On workstations this is how 32-bit and 64-bit support is provided. This can also be used to install armhf packages on an x86 based workstation.
This cross compile environment can link to a shared library from the Debian root. The package would be installed in Debian on the workstation to provide headers and libraries. This is included in most "-dev" packages. When run on the arm target it will also need a copy of the library installed, but it does not need the -dev package.
apt-get install libcurl4-openssl-dev:armhf
# Download the simple.c example from curl:
wget https://raw.githubusercontent.com/bagder/curl/master/docs/examples/simple.c
# After installing the supporting library, curl will link as compiling on the unit.
arm-linux-gnueabihf-gcc simple.c -o simple -lcurl
Copy the binary to the target platform and run on the target. This can be accomplished with network protocols like NFS, SCP, FTP, etc.
If any created binaries do not rely on hardware support like GPIO or CAN, they can be run using 'qemu'.
# using the hello world example from before:
./hello-world
# Returns Exec format error
apt-get install qemu-user-static
./hello-world
Debian Installing New Software
Debian provides the apt-get system which allows management of pre-built applications. The apt tools require a network connection to the internet in order to automatically download and install new software. The update command will download a list of the current versions of pre-built packages.
apt-get update
A common example is installing Java runtime support for a system. Find the package name first with search, and then install it.
root@ts:~# apt-cache search openjdk default-jdk - Standard Java or Java compatible Development Kit default-jdk-doc - Standard Java or Java compatible Development Kit (documentation) default-jdk-headless - Standard Java or Java compatible Development Kit (headless) default-jre - Standard Java or Java compatible Runtime default-jre-headless - Standard Java or Java compatible Runtime (headless) jtreg - Regression Test Harness for the OpenJDK platform libreoffice - office productivity suite (metapackage) openjdk-8-dbg - Java runtime based on OpenJDK (debugging symbols) openjdk-8-demo - Java runtime based on OpenJDK (demos and examples) openjdk-8-doc - OpenJDK Development Kit (JDK) documentation openjdk-8-jdk - OpenJDK Development Kit (JDK) openjdk-8-jdk-headless - OpenJDK Development Kit (JDK) (headless) openjdk-8-jre - OpenJDK Java runtime, using Hotspot JIT openjdk-8-jre-headless - OpenJDK Java runtime, using Hotspot JIT (headless) openjdk-8-jre-zero - Alternative JVM for OpenJDK, using Zero/Shark openjdk-8-source - OpenJDK Development Kit (JDK) source files uwsgi-app-integration-plugins - plugins for integration of uWSGI and application uwsgi-plugin-jvm-openjdk-8 - Java plugin for uWSGI (OpenJDK 8) uwsgi-plugin-jwsgi-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8) uwsgi-plugin-ring-openjdk-8 - Closure/Ring plugin for uWSGI (OpenJDK 8) uwsgi-plugin-servlet-openjdk-8 - JWSGI plugin for uWSGI (OpenJDK 8) java-package - Utility for creating Java Debian packages
In this case, the wanted package will likely be the "openjdk-8-jre" package. Names of packages can be found on Debian's wiki pages or the packages site.
With the package name apt-get install can be used to install the prebuilt packages.
apt-get install openjdk-8-jre
# More than one package can be installed at a time.
apt-get install openjdk-8-jre nano vim mplayer
For more information on using apt-get refer to Debian's documentation here.
Debian Setting up SSH
To install the SSH server, install the package with apt-get:
apt-get install openssh-server
Debian Stretch by default disallows logins directly from the user "root". Additionally, SSH will not allow remote connections without a password or valid SSH key pair. This means in order to SSH to the device, a user account must first be created, and a password set:
useradd --create-home --shell /bin/bash newuser
passwd newuser
After this setup it is now possible to connect to the device as user "newuser" from a remote PC supporting SSH. On Linux/OS X this is the "ssh" command, or from Windows using a client such as PuTTY.
Debian Starting Automatically
A systemd service can be created to start up headless applications. Create a file in /etc/systemd/system/yourapp.service
[Unit]
Description=Run an application on startup
[Service]
Type=simple
ExecStart=/usr/local/bin/your_app_or_script
[Install]
WantedBy=multi-user.target
If networking is a dependency add "After=network.target" in the Unit section. Once you have this file in place add it to startup with:
# Start the app on startup, but will not start it now
systemctl enable yourapp.service
# Start the app now, but doesn't change auto startup
systemctl start yourapp.service
| Note: | See the systemd documentation for in depth documentation on services. |