User Interface

The RPi_UI PCB

This is the documentation page for the RPi_UI board. That can be found in the BitWizard shop.

Installation

See Setting up I2C/SPI under Linux

External resources

Datasheets

• MCP79412 (I2C RTC)
• MCP79522 (SPI RTC)
• MCP9700 thermistor

Additional software

The Bw_tool is meant to provide a basic commandline access to the bitwizard expansion boards

Pinout

The 26 pin gpio connector is described at elinux
The SPI connector has the same pinout as the atmel 6-pin ICSP connector and is documented here: SPI_connector_pinout.
The I2C connector is documented here: I2C_connector_pinout.
The UART connector is documented here: uart connector pinout.
The analog connector has the following pinout:

pin	function
1	5V
2	Analog in
3	GND

Some people report they find it difficult to read the names of the connectors on the PCB. We'll fix that in a future version. In the meanwhile:

The RPi_UI PCB

Note that for the 20x4 version of the board, the connectors are in the same order with the same pinout.

LEDs

The only LED is a power indicator.

Jumper settings

There is one 2x2 pin jumper (JP1), which controls which SPI bus (actually which SPI chip-select line) is routed to the AVRs slave-select pin, and which is routed to the reset pin (to enable reprogramming of the AVR):
Left pads/pins connected: SPI0 connected to Slave-Select Right pads/pins connected: SPI1 connected to RESET Bottom pads/pins connected: SPI0 connected to RESET Top (near the LCD) pads/pins connected: SPI1 connected to Slave-Select

The recommended configuration is to have 1-3 connected. The pins 1 and 2 are marked on the PCB. So 1-3 means the jumper is closest to the board edge, running from the "1" to the "J" of "JP1".

People with the buttons/LCD on I2C can/should not install any jumpers here.

There is also one solder jumper, SJ1, which controls the supply voltage on the SPI, I2C, and UART connectors:
1-2: 5V (left)
2-3: 3V3 (right, near the PCB edge)

We deliver this jumper in the "5V" position with a small PCB trace. If you want to switch to 3.3V you'll have to cut the small trace with a knife.

Protocol

To make the RPI_UI PCB do things, you need to send things over the SPI or I2C bus to the PCB. A comparison of the two protocols can be found here.

The general overview of the SPI protocol is here.

the list of the default addresses is here.

The software

Controlling the display works the same way as our SPI_LCD or I2C_LCD modules. Reading the pushbuttons is very much like the DIO module. The read and write ports are described below.

Write ports

Some ports just set a single value. So writing more than one byte to such a port is redundant. Other ports are logically a stream of bytes. So writing more than one byte is encouraged.

The rpi_ui board defines several ports.

port	function
0x00	display data.
0x01	write data as command to LCD.
0x08	Set startup message line 1. After setting the startup message please wait 100ms before sending the next line. works from version 1.6+
0x09	Set startup message line 2.
0x0a	Set startup message line 3.
0x0b	Set startup message line 4.
0x10	any data clears the screen.
0x11	move the cursor to line l, position p. l is the top 3 bits p is the bottom 5 bits of the data.
0x12	set contrast.
0x13	set backlight.
0x14	reinit LCD. The initialzation procedure of the LCD takes a long time. A timed delay of about 500ms is in order after issuing this command
0x15	send 0 to set overrun-status back to zero.
0x17	Set the boot-time backlight intensity. (0xff means: use programmed default (0xc0))
0x20	set display number-of-lines. These are passed on to the display software, but seem to have little effect.
0x21	set display number-of-characters.
0x70 .. 0x71	Select which i/o is coupled to which ADC channel
0x80	Set number of ADC channels to read
0x81	Set number of samples to add (we suggest using a power of 2) (two bytes) See: annoying bug
0x82	Set ammounts of bits to shift accumulated sample value
0xf0	change address. But need to unlock first. See below. Might require a reboot to take effect.
0xf1	change address: unlock phase 1: write 0x55 here to start unlocking.
0xf2	change address: unlock phase 2: write 0xaa here to allow changing of the address (after writing 0x55 to f1).

Read ports

The rpi_ui board supports several read ports:

port	function
0x01	identification string. (terminated with 0).
0x02	read eeprom (serial number).
0x12	contrast
0x13	backlight intensity
0x15	read FIFO(first in, first out) overrun status. If different from previous value, you've had an overrun. Best to clear the screen and resend any data you want displayed.
0x16	read FIFO bytes-in-buffer. The fifo is 32 bytes, So you can send 20 chars to display if the value is less than 12.
0x17	read stored backlight intensity.
0x20	read button 1 (1 means NOT pushed, 0 means pushed)
0x21	read button 2 (1 means NOT pushed, 0 means pushed)
0x22	read button 3 (1 means NOT pushed, 0 means pushed)
0x23	read button 4 (1 means NOT pushed, 0 means pushed)
0x24	read button 5 (1 means NOT pushed, 0 means pushed)
0x25	read button 6 (1 means NOT pushed, 0 means pushed)
0x30	reports which buttons have been pushed since last read of this register If you keep a button pushed, it will read out as 1 multiple times
0x31	reports which buttons have been pushed since last read of this register (V1.2 and up) If you keep a button pushed, it will read out as 1 only once
0x40	read button 1 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x41	read button 2 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x42	read button 3 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x43	read button 4 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x44	read button 5 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x45	read button 6 (1 means pushed, 0 means NOT pushed) (V1.1 and up)
0x60.. 0x61	Return analog value (2 bytes)
0x68 .. 0x69	Return added and bitshifted analog value (2 bytes)
0x70 .. 0x71	Return which i/o is coupled to which ADC channel
0x80	Return number of ADC channels to read
0x81	Return number of samples to add (two bytes)
0x82	Return ammounts of bits to shift accumulated sample value

Using the analog inputs

Please see this chapter on the page explaining the DIO protocol. There are two major differences:

• The internal reference voltage needs to be configured in a different way
• The mapping of the analog inputs; please use the following table instead:

IO pin	value
temp	0xC7 (Vref=1V1) OR 0x47 (Vref=Vcc=~5V)
ext	0xC6 (Vref=1V1) OR 0x46 (Vref=Vcc=~5V)

Example

Setup the ADC (only needed once after reboot):

bw_tool -a 94 -w 70:c7 //Set ADC channel 0 to temperature sensor, and internal 1V1 reference
bw_tool -a 94 -w 80:01 //Set number of channels to sample to 1

Read the value:

bw_tool -a 94 -R 60:s // Read the result, output in hex

Using the temperature sensor

The temperature sensor is a MCP9700. It's output voltage depends on the temperature. For more information, please see the MCP9700 datasheet.

An initialization and readout script are available on the Temperature sensor example page.

Using the RTC

We first designed the User Interface to be equipped with either an SPI RTC or an I2C RTC. In practice the driver for the i2c version was a lot easier, so we're not selling the ones with the SPI RTC unless you really, really want (and we haven't run out of boards by then).

I2C

The I2C RTC has a Linux driver, which is available in the standard kernels delivered with raspian. (and probably others too).

Just use:

modprobe i2c:mcp7941x
echo mcp7941x 0x6f > /sys/class/i2c-dev/i2c-1/device/new_device

and the module is loaded and detects the RTC.

You can then set the RTC with: "hwclock -w". This will write the unix clock to the RTC. Put a "hwclock -s" somewhere in your startup scripts to initialize the unix clock from the RTC. The version 1 raspberry pi's had the i2c-0 bus on the gpio connector, you for the older raspberry pi you'll need to change i2c-1 into i2c-0..

SPI

We are not aware of a device driver for the SPI version of the RTC. We can read/write the RTC with bw_tool from the command line using the raw SPI bytes command line option "--hex". The CPU on the board has to enable the CS line for the SPI RTC. This limits the speed of the SPI transactions a bit (50 kHz has been verified working).

 bw_tool -s 50000 --hex 96 12 20 1 2 34 5 6 7 89

will write (0x12) the test-bytes 1 2 34 5 6 7 89 to the RAM at location 0x20 in the RAM.

 bw_tool -s 50000 --hex 96 13 20 0 0 0 0 0 0 0 0

will read them back.

Refer to the datasheet of the MCP79522 for information on the registers of the chip http://ww1.microchip.com/downloads/en/DeviceDoc/22300A.pdf

Examples

Read identification

read the identification string of the board.

data sent	data recieved	explanation
0x95	xx	select destination with address 0x94 for READ.
0x01	xx	identify
xx	0x73	's'
xx	0x70	'p'
xx	0x69	'i'
xx	...	etc.

Send text to display

Display the string "Hello World!" (only the first 5 bytes of the string shown).

data sent	data recieved	explanation
0x94	xx	select destination with address 0x94 for WRITE
0x00	xx	datastream
0x48	xx	'H'
0x65	xx	'e'
0x6c	xx	'l'
0x6c	xx	'l'
0x6f	xx	'o'
xx	...	etc.

Set cursor position

move to line 1, character 5:

data sent	data recieved	explanation
0x94	xx	select destination with address 0x94 for WRITE
0x11	xx	port 0x11 = set cursor position.
0x25	xx	0x25 = 001 00101 = line 1 position 5.

Bash script to show system informations

This bash script shows the current time and load averages of the cpu. The refresh is set to 5 seconds.

#!/bin/bash

# What display to use: 
DISPL="bw_tool -I -D /dev/i2c-1 -a 94"
# e.g. for SPI use: 
#DISPL="bw_tool -D /dev/spidev1.0 -a 94"

#clean the display
$DISPL -W 10:0:b

while true; do
       #get cpu loads
       load=`cut -d' ' -f-3 /proc/loadavg`
   
       #print the current time 
       $DISPL -W 11:00:b
       $DISPL -t `date +%H:%M:%S`

       #print the load averages
       $DISPL -W 11:20:b
       $DISPL -t $load

       #idle for 5 seconds
       sleep 5
done

Changelog

1.0

• Initial public release