This chapter gives a short overview of how to access the different hardware parts and interfaces from within the Linux operating system. It is written universally in order to fit all SECO Northern Europe platforms in general.

Machine type

The SECO Northern Europe i.MX6 based platforms are generally very similar and run the same OS versions. If it is needed to find out the actual hardware that the software is run on, it can be read out using the command line.

root@santaro:/# cat proc/cpuinfo

processor       : 0
model name      : ARMv7 Processor rev 10 (v7l)
BogoMIPS        : 3.00
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpd32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x2
CPU part        : 0xc09
CPU revision    : 10

processor       : 1
model name      : ARMv7 Processor rev 10 (v7l)
BogoMIPS        : 3.00
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpd32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x2
CPU part        : 0xc09
CPU revision    : 10

Hardware        : Garz & Fricke SANTARO (i.MX6)
Revision        : 63015
Board revision  : 1.2
Serial          : 03515530

FNGBoot         : 13.0r3797

Ethernet

If all network devices are properly configured as described in the manual, they can be used by the POSIX socket API.

There is a huge amount of documentation about socket programming available. Therefore it is not documented here.

The POSIX specification is available here.

Serial interfaces (RS-232 / RS-485 / MDB)

Most of the serial interfaces are exported as TTY devices and thus accessible via their device nodes under /dev/ttymxc<number>. Depending on your hardware platform (and maybe its assembly option), different transceivers (RS232, RS485, MDB) can be connected to these TTY devices. See the following table for the mapping between device nodes and hardware connectors on i.MX6:

RS485 can be used in half duplex or full duplex mode. This mode has to be set on the hardware (see the according hardware manual) as well as in the software. Per default, the interface is working in full duplex mode.

#include <linux/serial.h>   // serial_rs485
#include <unistd.h>         // close
#include <fcntl.h>          // O_RDWR, O_SYNC
#include <sys/ioctl.h>      // ioctl, TIOCSRS485

void set_rs485_half_duplex_mode()
{
    struct serial_rs485 rs485;
    int fd;
    /* Open port */
    fd = open ("/dev/ttymxc2", O_RDWR | O_SYNC);
    /* Enable RS485 half duplex mode */
    rs485.flags = SER_RS485_ENABLED | SER_RS485_RTS_ON_SEND;
    ioctl(fd, TIOCSRS485, &rs485);
    close(fd);
}

int main(void)
{
    set_rs485_half_duplex_mode();
    return 0;
}

Real Time Clock (RTC)

All SECO Northern Europe systems are equipped with a hardware real time clock. The system time is automatically set during the boot sequence by reading the RTC.

root@santaro:~# hwclock --show
Thu Apr 14 14:51:12 UTC 2022

root@santaro:~# timedatectl set-time "2022-11-02 16:26:00"
root@santaro:~# hwclock --systohc

Keypad connector

The so called keypad connector is a general purpose connector. It can be used in different modes. The mode is selected using the kernel command line. See [Kernel command line] on how it can be modified.

The actual pin mapping is described in the hardware guide for your device.

There are three available functions.

keypad=gpio

/sys/class/gpio/gpio<pin-number>

keypad=i2c

/dev/i2c-1

keypad=spi

/dev/spidev0.0
/dev/spidev0.1
/dev/spidev0.2

keypad=gpio,i2c,spi

keypad=gpio,i2c

SPI

There are two ways of controlling SPI bus devices from a Linux system:

• Writing a kernel SPI device driver and accessing this driver from user space by using its interface.

• Accessing the SPI bus via the Linux kernel’s spidev API directly.

Describing the process of writing a Linux SPI device driver is out of the scope of this manual. The AT25 SPI eeprom can serve as a good and simple example for such a driver. It is located in the kernel directory under:

• drivers/misc/eeprom/at25.c

The interface provided to the user space by such a kernel driver depends on the sort of this driver (e.g. character misc driver, input subsystem device driver, etc.). A very common usecase for an SPI driver is a touchscreen driver that uses the input event subsystem.

Accessing the SPI bus from userspace directly via spidev is described in the Linux kernel documentation and available in the kernel directory under:

• Documentation/spi/spidev

Additionally, there is an example C program available in the same location:

• Documentation/spi/spidev_test.c

The header for spidev is available under:

• include/linux/spi/spidev.h

I2C

There are two ways of controlling I2C bus devices from a Linux system:

• Writing a kernel I2C device driver and accessing this driver from user space by using its interface.

• Accessing the I2C bus via the Linux kernel’s i2c-dev API directly.

Describing the process of writing a Linux I2C device driver is out of this scope of this manual. The AT24 I2C EEPROM can serve as a good and simple example for such a driver. It is located in the kernel directory under:

• drivers/misc/eeprom/at24.c

The interface provided to the user space by such a kernel driver depends on the sort of this driver (e.g. character misc driver, input subsystem device driver, etc.). A very common usecase for an I2C driver is a touchscreen driver that uses the input event subsystem.

Accessing the I2C bus from userspace directly via i2c-dev is described in the Linux kernel documentation and available inside the kernel directory under:

• Documentation/i2c/dev-interface

The header for i2c-dev is available under:

• include/linux/i2c-dev.h

CAN

CAN bus devices are controlled through the SocketCAN framework in the Linux kernel. As a consequence, CAN interfaces are network interfaces. Applications receive and transmit CAN messages via the BSD Socket API. CAN interfaces are configured via the netlink protocol. Refer to the hardware manual corresponding to your device to find the physical port location..

root@santaro:~# ip link set can1 type can bitrate 125000
root@santaro:~# ifconfig can1 up

The structure for a CAN message is defined in the kernel header include/linux/can.h:

struct can_frame {
  u32 can_id; /* 29 bit CAN_ID + flags */
  u8 can_dlc; /* data length code: 0 .. 8 */
  u8 data[8];
};

int iSock;
struct sockaddr_can addr;

iSock = socket(PF_CAN, SOCK_RAW, CAN_RAW);

addr.can_family = AF_CAN;
addr.can_ifindex = if_nametoindex("can0");

bind(iSock, (struct sockaddr *)&addr, sizeof(addr);

struct can_frame frame;

frame.can_id = 0x123;
frame.can_dlc = 1;
frame.data[0] = 0xAB;

nbytes = write(iSock, &frame, sizeof(frame));

struct can_frame frame;

nbytes = read(iSock, &frame, sizeof(frame));

if (nbytes > 0) {
  printf("ID=0x%X DLC=%d data[0]=0x%X\n",
  frame.can_id,
  frame.can_dlc,
  frame.data[0]);
}

root@santaro:~# cansend can1 -i 0x20 0xca 0xbe 0xca 0xbe

root@santaro:~# candump can1

A more detailed documentation of the CAN bus handling in the Linux kernel can be found in the documentation directory of the Linux kernel source tree.

USB

There are two general types of USB devices:

• USB Host: the Linux platform device is the host and controls several devices supported by corresponding Linux drivers.

• USB Device: the Linux platform device acts as a USB device itself by emulating a specific device type.

USB Host

For USB Host functionality, SECO Northern Europe platforms per default support the following devices:

• USB Mass Storage

• USB Keyboard

There are many more device drivers available in the Linux kernel. They are not activated by default, because SECO Northern Europe cannot maintain and test the huge amount of existing drivers. Instead, the customer may do this themselves or engage SECO Northern Europe to implement their special use case. Existing drivers can easily be activated by reconfiguring and rebuilding the Linux kernel inside the BSP.

The USB Host bus can also be directly accessed by using libusb. This library is installed on SECO Northern Europe platforms per default. Further information can be found here.

USB Device

For USB Device functionality, the following device emulations are supported per default:

• USB Serial Gadget

Again, further drivers can be activated by reconfiguring the Linux kernel. The USB Device drivers are not compiled into the kernel by default, but are located as modules in the file system. In order to use the Serial Gadget for example, the according module has to be loaded:

root@santaro:~# modprobe g_serial

The Serial Gadget creates a virtual serial port over USB, accessible via the device node /dev/ttyGS0.

SD cards and USB mass storage

SD cards and USB mass storage devices can be accessed directly by using their devices nodes. The SD card can be found under /dev/mmcblk1, its single partitions are located under /dev/mmcblk1pX with X being a positive number. The USB mass storage devices can be found under /dev/sdX with X=a..z, its single partitions under /dev/sdXY with Y being a positive number

root@santaro:~# mkfs.vfat /dev/mmcblk1p1

root@santaro:~# mkdir /my_sdcard
root@santaro:~# mount /dev/mmcblk1p1 /my_sdcard

root@santaro:~# mkdir /my_usb_drive
root@santaro:~# mount /dev/sda1 /my_usb_drive

Temperature Sensor

Most SECO Northern Europe systems are equipped with an on-board hardware temperature sensor. The sensor is a Texas Instruments LM75 connected via I²C. To measure the current temperature you can read the corresponding sysfs file in /sys/class/hwmon/hwmon0/.

root@santaro:~# cat /sys/class/hwmon/hwmon0/temp1_input
23500

root@santaro:~# cat /sys/class/hwmon/hwmon0/temp1_max_alarm
1

Touchscreen

The touchscreen device is used by the window manager (a Wayland compositor) using libinput which itself accesses the touchscreen via the Linux input subsystem kernel API, i.e. its device node /dev/input/event0. Applications ( i.e. based on Qt) get the input events from the compositor.

Calibration for touchscreens, which is mandatory for resistive touchscreens but also useful for capacitive ones, is done by libinput internally.

ts_calibrate

touchcal-conv to-udevrule
sync

Audio

SECO Northern Europe systems with an integrated audio codec make use of ALSA (Advanced Linux Sound Architecture) as a software interface. This project includes a user-space library (alsa-lib) and a set of tools (aplay, arecord, amixer, alsactl) for controlling and accessing the audio hardware from user applications or the console. Please refer to the official ALSA webpage for a full documentation.

root@santaro:~# aplay my_audio_file.wav

root@santaro:~# arecord -f cd -t wav > my_recorded_audio_file.wav

root@santaro:~# amixer sset 'PCM' 50%

HDMI

The HDMI port can be used as primary or secondary display of the device. Furthermore, an audio-enabled HDMI device can be used as secondary sound card.

There are a few different use case for the HDMI display:

• HDMI as primary display

• HDMI as secondary display

• HDMI as mirror of the internal display

Depends on configurations, different settings for the HDMI output can be configured by an xml file. See the chapter [Initial Device Configuration] for further instructions.

Display power

The display can be powered on or off by software. The value is exported as a virtual file in the sysfs under /sys/class/backlight/backlight/bl_power. It can be accessed using the standard file operations open(), read(), write() and close().

root@santaro:~# echo 1 > /sys/class/backlight/backlight/bl_power
root@santaro:~# echo 0 > /sys/class/backlight/backlight/bl_power

Display backlight

The brightness of the display backlight can be adjusted in a range from 0 to a maximum level. The value is exported as a virtual file in the sysfs under /sys/class/backlight/backlight/brightness. It can be accessed using the standard file operations open(), read(), write() and close().

root@santaro:~# cat /sys/class/backlight/backlight/brightness
1
root@santaro:~# cat /sys/class/backlight/backlight/max_brightness > /sys/class/backlight/backlight/brightness