IMPORTANT: Please note that the Linux GPIO numbers above are different from both the physical pin numbers and the UP pinout. The Linux GPIO numbers are assigned to match the Raspberry Pi BCM GPIO numbering scheme.

For comparison with Raspberry Pi layouts, visit: http://pinout.xyz

Warning: Pin 26 is currently stuck in SPI0_CS1 functionality and it cannot be exported to GPIO. The issue will be solved in a future kernel release.

• The X5-Z8300 SoC includes 4 GPIO controllers which provide up to 187 GPIOs (depending on SKU), via pads which are shared with other functions such as I2C, SPI, etc.

• These can be individually configured as inputs or outputs, and can generate edge- or level-triggered interrupts. However, since the X5-Z8300 uses 1.8V I/O, and is not capable of sinking or sourcing significant amounts of current, these cannot be connected directly to the external 40-pin I/O header where they may be used to drive LV-TTL or LV-CMOS electronics at 3.3V. Therefore, each of the 28 GPIO pins exposed on the 40-pin header are connected to the X5-Z8300 via a 74LVC1T45 level translator (a.k.a buffer), which translates between the 1.8V signal of the SoC and the 3.3V required at the external pin header as well as providing 24mA current source/sink capacity.

• The level translators include a direction control pin which is used to select input or output mode. This needs to be controlled by software so that the user can select the mode in which they wish to use the GPIO pin. Therefore, these control signals are driven by a pair of 16-bit PCA9555 I2C GPIO expanders.

• In addition, 74LVC1T45 level translators are designed for push-pull applications (e.g. GPIO, SPI) and not suitable for open-drain applications (e.g. I2C). For this reason, NTS0104 level translators are also used on the I2C-capable pins along with a 74CBTLV3125 4-bit switch to dynamically select between the push-pull or the open-drain level translators for the I2C-capable header pins.

• While all of this may sound a bit complex, the good news is that this is managed transparently for the end-user by a driver in the Linux kernel which is included with the ubilinux distribution for UP. A pinctrl/gpio driver developed for the UP board presents a set of 28 "virtual" GPIO pins to the user via standard kernel interfaces. When the user enables and configures one of these GPIO pins, the driver transparently configures the level translators and switches as needed.

There are some limitations and considerations which the user should be aware of:

• The level-shifters are configured as outputs by default at power-on and may be driving a high output signal (3.3V). This may have implications for users who are connecting external electronics such as motor drivers. This will be addressed in the final production version of the UP board.

• Some of the SoC GPIO pins and the corresponding level translators and switches on the UP board support alternate functions such as I2C, SPI, etc. In general, the pin will be configured by default for the alternate function at boot time if the corresponding controller (e.g. I2C-1) is enabled in the BIOS. Otherwise, the pin will be configured for GPIO. Even so, if the user enables the pin for GPIO mode at run-time, the pin will be automatically reconfigured as such.  More information can be found on: Pinout.

• The SoC GPIO pins include configurable internal pull-up resistors, but these are not really effective when the level translators are configured in input mode. If pull-up or pull-down resistors are needed for stabilizing floating input signals on a header pin, the user would need to include these in the external circuit connected to the UP board.

• When used as interrupt triggers, please be aware that there is no debounce logic included. If connecting to an input that does not produce a clean logic transition (e.g. a mechanical switch), then the user may want to consider adding some debounce logic at either the hardware or software level. The following article has some great general information on de-bouncing switch inputs: http://www.ganssle.com/debouncing.htm

The GPIOs may be used through the standard GPIO programming APIs provided by the Linux kernel.

This includes the sysfs interface described here: https://www.kernel.org/doc/Documentation/gpio/sysfs.txt. Note that the GPIO pins for the external headers are numbered 0-27 in Linux (refer to the above Pinout table for the exact mapping).

In addition, the following popular Python libraries have been ported to allow the GPIO pins to be used easily from Python scripts and to aid application porting from other similar platforms:

• libMRAA
• RPi.GPIO

A total of 28 independent GPIO pins are provided on the I/O header. Our Kernels for Ubuntu and Yocto include the kernel platform drivers developed for the UP board to provide Linux GPIO pin numbering in the range 0-27, emulating that of the Raspberry Pi.

Please make sure to execute the following commands as root (not with sudo) or enable access from userspace following these steps.

To configure physical pin 37 above (Linux GPIO number 26) as an output pin and then set the output level high:

echo 26 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio26/direction
echo 1 > /sys/class/gpio/gpio26/value

1 high-speed UART (UART1) is provided on the I/O header at pins 8 (TXD) and 10 (RXD).

It supports baud rates between 300 and 3686400. RTS/CTS hardware flow-control pins for this UART are also exposed at pins 11 (RTS) and 36 (CTS).

An additional debug UART0 is also available on connector CN7 at the front edge of the board, intended to be used for serial access to BIOS and OS. For details, see Serial console.

To configure UART 1 for raw data transfer, with no flow control, at 115200 bps:

stty -F /dev/ttyS4 115200 raw -echo -echoe -echok -crtscts

To send a raw string to a remote device via UART1 (header pin 8):

echo "Hello World" > /dev/ttyS4

To receive and display a raw string from a remote device via UART 1 (header pin 10):

cat /dev/ttyS4

On ubilinux, the /dev/ttyS4 device is also aliased as /dev/ttyAMA0 to aid software portability for Raspberry Pi applications.

• 2 fast-mode (100 kHz and 400 kHz) I²C ports are provided on the I/O header.

I2C device as 808622C1:01 controller in Linux can be identified. We can check the I2C bus number checking the PCI device number for I2C:

 ls /sys/devices/pci0000:00/808622C1:01/

 driver  driver_override  firmware_node  i2c-5  modalias  power  subsystem  uevent

Then, we only need to connect our I2C slave device to the right physical pins (3 and 5, as I2C1_SDA and I2C1_SCL).

Finally, to detect your device in the I2C bus, you could use the i2cdetect tool:

 sudo apt install i2c-tools

 i2cdetect -r -y 5

      0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
 00:          --  04 -- -- -- -- -- -- -- -- -- -- -- 
 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
 70: -- -- -- -- -- -- -- --

To write a 2 byte value (0xFF 0xF0) to register offset 0x40 of an I²C device (address 0x60) connected to pins 3, 5:

sudo i2cset -y 5 0x60 0x40 0xFF 0xF0 i

This requires the i2c-tools software package, available with most Linux distributions and installed by default in ubilinux.

• 1 SPI port, supporting clock speeds up to 25MHz, is provided on the I/O header.

• 2 PWM ports, supporting frequencies between 293 Hz and 75 kHz with an 8-bit duty-cycle resolution, are provided on the I/O header.

To generate a 293 Hz square wave pulse on pin 32, with a duty cycle of approximately 50%, execute the following commands as root:

echo 0 > /sys/class/pwm/pwmchip0/export
echo 3413333 > /sys/class/pwm/pwmchip0/pwm0/period
echo 1706667 > /sys/class/pwm/pwmchip0/pwm0/duty_cycle
echo 1 > /sys/class/pwm/pwmchip0/pwm0/enable

The UP Board includes 3 LEDs (yellow, green, red) on the underside of the board (underneath the 4 USB2.0 Type-A sockets), which are controlled by the pin control CPLD on the board. As root, you can use the following commands to control the LEDs:

echo 1 > /sys/class/leds/upboard\:green\:/brightness

echo 0 > /sys/class/leds/upboard\:green\:/brightness

For other LEDs, replace "green" with "red" or "yellow" in the commands above.