Duckbill BSP DocumentationRelease 1.0
I2SE GmbH
Mar 17, 2021
Contents
1 Duckbill 2 31.1 General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Pin muxing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 UARTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.6 I2C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.7 ADC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.8 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.9 Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.10 SD card slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.11 Preinstalled packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.12 FAQs/Howtos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.13 Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2 Duckbill 2 485/Duckbill 2 485+ 112.1 LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 RS-485 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Duckbill 2 EnOcean 133.1 LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 EnOcean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Duckbill 2 SPI 154.1 LEDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.2 SPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.3 Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
i
ii
Duckbill BSP Documentation, Release 1.0
This document helps you to get familiar with the Board Support Package of Duckbill, that is the default firmwarewhich is pre-installed on the internal eMMC on Duckbill 2 based devices or can be flashed to SD cards (for formerDuckbills).
This document only describes the Board Support Package revision 2.x; the former Board Support packages are notsupported anymore. We strongly recommend to upgrade your application to this new BSP since it is much simplerthan the former one.
Since Duckbill and Duckbill 2 are very similar, this document focuses the differences only where really needed. In allother cases, there is no weighting on this point.
It is assumed, that the reader is at least familiar with Linux on desktop systems.
This BSP documentation applies to several product variants:
• Duckbill 2
• Duckbill 2 485/Duckbill 2 485+
• Duckbill 2 EnOcean
• Duckbill 2 SPI
Contents 1
Duckbill BSP Documentation, Release 1.0
2 Contents
CHAPTER 1
Duckbill 2
1.1 General information
This BSP consists of several software components:
• U-Boot (based on v2015.10)
• Linux kernel (based on v4.2.5)
• Root filesystem (based on Debian Jessie 8.2)
These components are tied together to build a single image file, which can be flashed to the internal eMMC or on SDcard.
1.2 Pin muxing
Some of the pins of the Duckbill connectors can be used for multiple purposes and/or share functionality with otherperipherals, e.g. SD card socket. This BSP configures the IO pin muxing according to the following image:
3
Duckbill BSP Documentation, Release 1.0
1.3 Login
To get shell access to the Duckbill, you can connect to the device via network using SSH protocol, or locally by usingthe Debug UART.
At both methods, a login prompt is presented. Default credentials are:
• username root
• password root
1.4 LEDs
The Duckbill is equipped with a two-color status LED at the bottom side. Each color of the LED is wired to a dedicatedGPIO pin of the CPU. As usual in Linux, both colors are modelled as individual LED in the BSP.
During boot process, U-Boot switches the red LED on shortly to indicate that a software component is running at all.When linux kernel takes over, it flashes the green LED like a heartbeat, to indicate that the kernel is still alive andrunning.
4 Chapter 1. Duckbill 2
Duckbill BSP Documentation, Release 1.0
Attribute Status LEDColor red greenLinux Device /sys/class/leds/duckbill:red:status /sys/class/leds/duckbill:green:statusDefault trigger none heartbeat
The following table lists various device states.
StatusLED
Durationof thisstate
Status / possible solution
red greenoff off persis-
tentDevice is powered off, attach power supply
on off < 10s U-Boot is running and loading Linuxon flash-
ing< 25s Linux kernel is booting
on off persis-tent
U-Boot could not start Linux, attach Debug UART to see U-Boot’s error message; checkU-Boot’s image and/or fdt_file environment settings and ensure, that these two files arepresent in the root filesystem below /boot
off flash-ing
persis-tent
Linux system is running
on flash-ing
persis-tent
Linux system is running, but errors during initialization
1.5 UARTs
The Duckbill comes with two UARTs on the pin headers. The Debug UART (part of connector 4) is usually usedas system console, while the second UART (part of connector 3) is used as application UART. Please note, that theDebug UART has 3.3 V level, so do not connect it directly to your PCs serial port. We recommend to use an USB toUART TTL level adapter; there are plenty products available.
Attribute Debug UART Application UARTFunction System console Customer definedLinux Device /dev/ttyAMA0 /dev/ttyAPP0Baudrate 115200 115200Data bits 8 8Parity None NoneStop bits 1 1Flow control None None
The settings listed above are default values. For the Debug UART, we do not recommend to change the settings.
The application UART uses only Rx and Tx lines by default, but not RTS/CTS. If your application required hardwareflow control, you have to modify the Device Tree binary to use the correct pin muxing on the additional required pins.In this case, you loose this/these pin(s) for other functionality.
1.6 I2C
The I2C interface (I2C0 at connector 3) is available as linux device /dev/i2c-0 and operating frequency is 100 kHz.The i2c-tools package is pre-installed so you can use this interface from linux userspace.
1.5. UARTs 5
Duckbill BSP Documentation, Release 1.0
1.7 ADC
The Duckbill comes with one ADC input pin (LRADC2 at connector 1). The low-level hardware driver registers itselfto Linux’s IIO subsystem (Industrial I/O subsystem) and thus this ADC pin is available as following device:
/sys/bus/iio/devices/iio:device0/in_voltage2_raw
1.8 Networking
The device has on ethernet interface onboard, which is called eth0 in the Linux system. It supports 10/100 Mbitconnections and MDI/MDI-X.
The following list mentions only some features a Linux system is capable of:
• IPv4
• IPv6
• Unix domain sockets
• TCP / UDP
• DHCP
• Ethernet Bridging
The Duckbill device comes with the following default network configuration:
Setting Value ValueLinux interface eth0 eth0:1IPv4 address via DHCP 169.254.12.53IPv4 netmask via DHCP 255.255.0.0Default gateway via DHCPDNS server via DHCP
These settings allow to integrate the Duckbill into every network with automatic configuration, but also provide anemergency fallback IP address in case you attach the Duckbill directly to a PC.
For a detailed description of all possible settings, please refer to the Debian network documentation.
1.9 Partitions
The default SD card/eMMC images contain two primary partitions:
Device Boot Start End Sectors Size Id Type/dev/mmcblk0p1 * 2048 4095 2048 1M 53 OnTrack DM6 Aux3/dev/mmcblk0p2 6144 3751935 3745792 1.8G 83 Linux
The first partition is required for the Freescale i.MX28 platform as it contains the boot stream, used by the i.MX28internal ROM to bring up the device. In our case, this partition contains U-Boot as bootloader. This partition isrequired to have the partition id 0x53 and is 1 MiB in size.
The second partition is a normal ext4 linux filesystem containing the root filesystem. It must also contain a subdirectory/boot in which the kernel zImage and one or multiple device tree files (e.g. imx28-duckbill-2.dtb) reside. Please note,
6 Chapter 1. Duckbill 2
Duckbill BSP Documentation, Release 1.0
that U-Boot will look after these files during boot, so when renaming files in this directory also update the U-Bootenvironment variables image and fdt_file accordingly.
Another important point to note is, that the second partition is created as a small partition of around 340 MB (thismay also vary depending on the product variant since various products include various packages pre-installed). Thenduring the first boot, the partition is resized on-the-fly to fill up the whole space available. This done to be able todistribute small images and to not depend on the exact size of the eMMC or SD card used (e.g. even two SD cardslabeled both with 2 GB may differ in exact size). One drawback of this approach is, that the device needs to rebootduring this first boot because the new partition size is not recognized by the linux kernel as the partition is busy.
U-Boot uses dedicated space to save various variables, the so called U-Boot environment. On Duckbill, there are twodifferent regions reserved in the eMMC/SD card for this U-Boot environment. When modifying the environment, onlyone region is updated, the other one is left unchanged so that there is always a valid copy of the U-Boot environment.Both regions are 128 kB each. The first region starts at offset 128 kB from the beginning of the eMMC/SD card, thesecond region starts at offset 256 kB, thus both regions are placed before the start of the first partition.
1.10 SD card slot
The devices are equipped with an additional SD card slot to store customer data. When an SD card is inserted, it isaccessible through the linux device /dev/mmcblk1, and if the SD card contains multiple partitions they appear as/dev/mmcblk1p1, /dev/mmcblk1p2 and so on.
Supported filesystems are FAT/FAT32 and ext2/3/4 by default.
Please note, that the filesystems on SD card are not automatically mounted, you can do this manually e.g. by
mount /dev/mmcblk1p1 /mnt
Do not forget to unmount the filesystem before removing the SD card, otherwise you will most likely loss data,depending on the filesystem you used.
Note 1: It is not possible to boot a Duckbill 2 device from SD card as it was possible for former Duckbill series.Duckbill 2 series devices always boot from internal eMMC flash (however, it would be possible to instruct U-Boot tonot load linux kernel/root filesystem from eMMC but from SD card).
Note 2: Support for the SD card slot was introduced with BSP v1.3 for Duckbill 2 and Duckbill 2 EnOcean, andwith BSP v1.4 for Duckbill 2 485/485+.
1.11 Preinstalled packages
The following list is incomplete and lists only important packages/tools (not including e.g. dependencies and/orDebian base packages):
• gcc 4.9
• perl 5.20
• autoconf
• autotools
• pkg-config
• binutils
• i2c-tools
• memtool
1.10. SD card slot 7
Duckbill BSP Documentation, Release 1.0
• sdimage
1.12 FAQs/Howtos
This Howto section describes some basic procedures on a running Duckbill device. For build-time FAQ/Howtos,please refer to the documentation of the used BSP project called STIB.
1.12.1 USB recovery mode
The USB recovery mode is activated when:
• Duckbill is powered on without a bootable image in the eMMC,
• PSWITCH is pressed for more than five seconds while ROM boot.
Note: During USB recovery mode the Duckbill LEDs are off
1.12.2 Flashing
The embedded eMMC flash can be programmed via Freescale’s Manufacturing Tool MfgTool (registration required).This uses the USB recovery mode of the i.MX28. In this mode the MfgTool transfers a small software into i.MX28’sRAM, which is able to access the eMMC flash.
Requirements:
• Windows PC with USB 2.0 interface
• Freescale MfgTool 1 for i.MX28
Note: USB 3.0 isn’t supported by MfgTool
Necessary steps:
• Extract the ZIP archive with the Linux image
• Copy the complete Duckbill directory ( e.g. Duckbill2_v1_2 ) into Freescale MfgTool Profile directory ( <Mfg-ToolInstallDir>/Profiles )
• Start Duckbill in USB recovery mode ( at first time this triggers a driver installation )
• Start MfgTool
• Press the button “Scan devices”
• After the Duckbill has been found the button on the right should be named as “Start” and green
• Select the profile ( is the same as the directory name copied above ) which should be flashed via the drop-downlist
• Now press the button “Start” and wait until the writing process has been finished
• Finally press the button “Stop” and disconnect Duckbill from USB
1.12.3 Update the Linux kernel
• Transfer the new linux kernel image (zImage) binary to the Duckbill.
• Replace the existing linux kernel image in /boot directory with the new one.
8 Chapter 1. Duckbill 2
Duckbill BSP Documentation, Release 1.0
• Reboot the Duckbill, so that the new kernel is used.
1.12.4 Update the Device Tree binary
• Transfer the new Device Tree binary file to the Duckbill.
• Replace the existing Device Tree binary in /boot directory with the new one.
• Please remember, that U-Boot looks for a device specific filename when booting, so either use the same filenameas of the replaced file, or adjust the U-Boot setting with:
fw_setenv fdt_file <new-file.dtb>sync
• Reboot the Duckbill, so that the new Device Tree is used.
1.12.5 Update U-Boot on the target device from running Linux
• Transfer the new U-Boot image file (u-boot.sb) to the Duckbill.
• Install it with the following command:
sdimage -f u-boot.sb -d /dev/mmcblk0sync
1.12.6 Modify U-Boot environment
The BSP comes with the U-Boot tools fw_printenv and fw_setenv pre-installed. Use fw_printenv to show all orindividual U-Boot environment variables and use fw_setenv to modify or delete them.
Both tools require the configuration file /etc/fw_env.config with the following content:
/dev/mmcblk0 0x20000 0x20000/dev/mmcblk0 0x40000 0x20000
This file tells both tools where to save the both redundant U-Boot environment regions within the eMMC/SD card,and how large both areas are.
1.12.7 Modify kernel command line parameters
U-Boot passes kernel command line arguments to linux kernel using the U-Boot environment variable bootargs. How-ever, on Duckbill this variable is constructed at run-time. So if you need to append some command line arguments,please extend the U-Boot variable mmcargs, e.g.:
fw_setenv mmcargs 'setenv bootargs console=${console},${baudrate} root=${mmcroot}→˓rootwait bootsys=${bootsys} panic=1 <something to append>'sync
Please note, that the default content of mmcargs contains variable names, so you have to quote these properly, other-wise your shell would try to expand the variables!
To make it easier during development, it is recommended to introduce a dedicated variable and to append solely areference to it, e.g.:
1.12. FAQs/Howtos 9
Duckbill BSP Documentation, Release 1.0
fw_setenv custom_args <something to append>fw_setenv mmcargs 'setenv bootargs console=${console},${baudrate} root=${mmcroot}→˓rootwait bootsys=${bootsys} panic=1 ${customargs}'sync
This way, you can focus on changing custom_args without worrying to always touch the longish mmcargs variable.
The mmcargs U-Boot variable shown above contains the factory default string used in U-Boot to build the kernelcommand line. So at runtime, the variable references are substituted and this results in a default kernel command line:
console=ttyAMA0,115200 root=/dev/mmcblk0p2 rootwait bootsys=1 panic=1
1.13 Sources
All sources for this BSP are available public on I2SE’s GitHub account: the STIB called project is used to generatedbootable image files which can be transfered to the internal eMMC and/or SD card.
For a custom image, you can use this project as a starting point and adopt it to your personal requirements.
10 Chapter 1. Duckbill 2
CHAPTER 2
Duckbill 2 485/Duckbill 2 485+
2.1 LEDs
The Duckbill is equipped with a two-color status LED at the bottom side. Each color of the LED is wired to a dedicatedGPIO pin of the CPU. As usual in Linux, both colors are modelled as individual LED in the BSP.
During boot process, U-Boot switches the red status LED on shortly to indicate that a software component is runningat all. When linux kernel takes over, it flashes the green status LED like a heartbeat, to indicate that the kernel is stillalive and running.
Attribute Status LEDColor red greenLinux Device /sys/class/leds/duckbill:red:status /sys/class/leds/duckbill:green:statusDefault trigger none heartbeat
The following table lists various device states.
Status LED Duration of this state Status / possible solutionred greenoff off persistent Device is powered off, attach power supplyon off < 10s U-Boot is running and loading Linuxon flashing < 25s Linux kernel is bootingon off persistent U-Boot could not start Linuxoff flashing persistent Linux system is runningon flashing persistent Linux system is running, but errors during initialization
Additionally, the Duckbill 485 has two single LEDs on left and right side of the case. The LEDs are handled bythe ser2net application via sysfs. They indicate RS-485 operations by flashing and are operational after a socketconnection to ser2net has been established.
11
Duckbill BSP Documentation, Release 1.0
Attribute TX LED RX LEDColor red greenLinux Device /sys/class/leds/duckbill:red:rs485 /sys/class/leds/duckbill:green:rs485Default trigger none none
2.2 RS-485
The Duckbill 485 has an application UART which is connected to the RS-485 interface.
Attribute Application UARTFunction RS-485 GatewayLinux Device /dev/ttyAPP0Baudrate 115200Data bits 8Parity NoneStop bits 1Flow control None
The BSP makes the UART available via a TCP socket on the Ethernet. The RFC2217 compatible network servicelistens on TCP port 5000.
Supported baudrates:
• 300
• 600
• 1200
• 2400
• 4800
• 9600
• 19200
• 38400
• 57600
• 115200
• 230400
12 Chapter 2. Duckbill 2 485/Duckbill 2 485+
CHAPTER 3
Duckbill 2 EnOcean
3.1 LEDs
The Duckbill is equipped with a two-color status LED at the bottom side. Each color of the LED is wired to a dedicatedGPIO pin of the CPU. As usual in Linux, both colors are modelled as individual LED in the BSP.
During boot process, U-Boot switches the red status LED on shortly to indicate that a software component is runningat all. When linux kernel takes over, it flashes the green status LED like a heartbeat, to indicate that the kernel is stillalive and running.
Attribute Status LEDColor red greenLinux Device /sys/class/leds/duckbill:red:status /sys/class/leds/duckbill:green:statusDefault trigger none heartbeat
The following table lists various device states.
Status LED Duration of this state Status / possible solutionred greenoff off persistent Device is powered off, attach power supplyon off < 10s U-Boot is running and loading Linuxon flashing < 25s Linux kernel is bootingon off persistent U-Boot could not start Linuxoff flashing persistent Linux system is runningon flashing persistent Linux system is running, but errors during initialization
Additionally, the Duckbill 2 EnOcean has three single LEDs on left side of the case. The red and green LED arehandled by the ser2net application via sysfs. They indicate EnOcean operations by flashing and are operational after asocket connection to ser2net has been established.
13
Duckbill BSP Documentation, Release 1.0
Attribute TX LED RX LEDColor red greenLinux Device /sys/class/leds/duckbill:red:enocean /sys/class/leds/duckbill:green:enoceanDefault trigger none none
The blue LED is free to use by custom applications.
Linux Device Color Default trigger/sys/class/leds/duckbill:blue:enocean blue none
3.2 EnOcean
The Duckbill EnOcean has an application UART which is connected to the EnOcean module TCM310.
Attribute Application UARTFunction EnOcean GatewayLinux Device /dev/ttyAPP0Baudrate 57600Data bits 8Parity NoneStop bits 1Flow control None
The BSP makes the UART available via a TCP socket on the Ethernet. The RFC2217 compatible network servicelistens on TCP port 5000.
14 Chapter 3. Duckbill 2 EnOcean
CHAPTER 4
Duckbill 2 SPI
4.1 LEDs
The Duckbill is equipped with a two-color status LED at the bottom side. Each color of the LED is wired to a dedicatedGPIO pin of the CPU. As usual in Linux, both colors are modelled as individual LED in the BSP.
During boot process, U-Boot switches the red status LED on shortly to indicate that a software component is runningat all. When linux kernel takes over, it flashes the green status LED like a heartbeat, to indicate that the kernel is stillalive and running. The red status LED represent the state of the SPI connection to the QCA7000.
Attribute Status LEDColor red greenLinux Device /sys/class/leds/duckbill:red:status /sys/class/leds/duckbill:green:statusDefault trigger none heartbeat
The following table lists various device states.
Status LED Duration of this state Status / possible solutionred greenoff off persistent Device is powered off, attach power supplyon off < 10s U-Boot is running and loading Linuxon flashing < 25s Linux kernel is bootingon off persistent U-Boot could not start Linuxoff flashing persistent Linux system is running, but no SPI connectionflashing flashing persistent Linux system is running and has a working SPI connection
4.2 SPI
The Duckbill SPI is intended to be used in the evaluation kit “PLC bundle for Internet of Things”. Thus the devicetree file contains a section which refers to the Qualcomm Atheros QCA7000 serial-to-powerline bridge.
15
Duckbill BSP Documentation, Release 1.0
The settings for the QCA driver are listed in the following table.
Attribute Source SSP2Type Modprobe config ExternalMAC address Device tree Value from OTPMax SPI clock rate Device tree 8 MHzActual SPI clock rate Clock tree 6 MHzSPI mode Device tree 3Expected SPI slave Device tree QCA7000Expected command mode Device tree burst
The device tree binding for the QCA driver can be found in the Kernel sources:Documentation/devicetree/bindings/net/qca-qca7000-spi.txt
Note 1: The MAC address is added dynamically by U-Boot into the device tree.
Note 2: The reference clock for SSP2 is switched from ref_io1 to ref_xtal by an additional kernel patch. This limitsthe maximum SPI frequency to 12 MHz. This is due to observed bit errors when ref_io1 is used as clock source.However, for the use-case with QCA7000, the maximum clock rate is already limited by the QCA7000 which onlysupports up to 12 MHz. The reason for the actual 6 MHz is, that the SPI leaves the Duckbill via the connector and“flying wires”.
Due the limitation of the selected clock and SPI the following SPI clock rates are available:
• 12.0 MHz
• 6.0 MHz
• 4.0 MHz
• 3.0 MHz
• 2.4 MHz
• 2.0 MHz
• 1.72 MHz
• 1.5 MHz
• 1.34 MHz
• 1.2 MHz
• 1.1 MHz
• 1.0 MHz
4.3 Networking
The device has on ethernet interface onboard, which is called eth0 in the Linux system. It supports 10/100 Mbitconnections and MDI/MDI-X.
The QCA driver provides an additional network interface, which is called eth1.
Both interfaces are bridged in Linux as interface br0.
The following list mentions only some features a Linux system is capable of:
• IPv4
• IPv6
16 Chapter 4. Duckbill 2 SPI
Duckbill BSP Documentation, Release 1.0
• Unix domain sockets
• TCP / UDP
• DHCP
• Ethernet Bridging
The Duckbill device comes with the following default network configuration:
Setting Value ValueLinux interface br0 br0:1IPv4 address via DHCP 169.254.12.53IPv4 netmask via DHCP 255.255.0.0Default gateway via DHCPDNS server via DHCP
These settings allow to integrate the Duckbill into every network with automatic configuration, but also provide anemergency fallback IP address in case you attach the Duckbill directly to a PC.
For a detailed description of all possible settings, please refer to the Debian network documentation.
4.3. Networking 17