duckbill bsp documentation · duckbill bsp documentation, release 1.0 this document helps you to...

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

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


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


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


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


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,


https://wiki.debian.org/NetworkConfiguration


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


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


https://github.com/I2SE/stib

https://www.nxp.com/webapp/Download?colCode=IMX_MFG_TOOL


• 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


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.


https://github.com/I2SE

https://github.com/I2SE/stib

CHAPTER 2

Duckbill 2 485/Duckbill 2 485+

2.1 LEDs


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.



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


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


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.



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


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


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.



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


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


• 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

https://wiki.debian.org/NetworkConfiguration

duckbill bsp documentation · duckbill bsp documentation, release 1.0 this document helps you to...

Documents