Getting Started

Both the 7" and 10.1" Touchberry Pi come with their SD card preloaded with the system image and factory settings, ready to use right out of the box. 

Programming the Touchberry

The Touchberry panels, based on a Raspberry Pi board, can be programmed just like a standard Raspberry Pi. Additionally, they have the added benefit of featuring a resistive touchscreen that enables tactile viewing and operation of the panel.

Node-RED

Node-RED comes pre-installed as default: It is a browser-based flow editor that enables graphical programming of hardware devices, APIs, and online services. It is built on top of Node.js, allowing full use of its event-driven non-blocking model.

Power supply

The Touchberry can be powered by a DC power source ranging from 12 to 24 Vdc, with a current of 2.5 A at 12Vdc and 1.25 A at 24Vdc. The panel can consume a maximum of 22 VAC.

Analog inputs

In analog inputs, the voltage difference between -Vcc (ground) and +Vcc can vary across a wide range of values. An analog input provides a measurement in the form of a digital value that is represented by an N-bit number. Both digital and analog I/O have self-insulation, which means that they can be connected to power supplies with different voltages than 24 V.

The Touchberry Panel provides 2 analog inputs (I-0 to I-1) which can be used with both modes (0-10V and 4-20mA). 

To read the value of the analog inputs, the Touchberry has a series of tests for this.

If we use the 4-20mA configuration (default), we will do it as follows:

pi@raspberrypi:~ $ ./test/4-20mA/get-analog-input I0
pi@raspberrypi:~ $ ./test/4-20mA/get-analog-input I1

If you have the analog input configured from 0 to 10V, it will be done like this:

pi@raspberrypi:~ $ ./test/analog/get-analog-input I0
pi@raspberrypi:~ $ ./test/analog/get-analog-input I1

Digital inputs

In digital inputs, the voltage difference between -Vcc (ground) and +Vcc can only be between two states: 0 (which corresponds to -Vcc or GND) or 1 (which corresponds to +Vcc), with no intermediate values. Both digital and analog I/O have self-insulation, which means that they can be connected to power supplies with different voltages than 24 V. 

The Touchberry Panel provides 3 digital inputs (I-2 to I-4) which can be used with both modes (5-24V and 250mA).

In order to measure the value of the digital input, we will use the tests that are precompiled in this way:

pi@raspberrypi:~ $ ./test/digital/get-digital-input I2
pi@raspberrypi:~ $ ./test/digital/get-digital-input I3
pi@raspberrypi:~ $ ./test/digital/get-digital-input I4

In this way it will return 0 or 1 in case of LOW 0 and in case of HIGH 1.

Digital outputs

Voltage variation from –Vcc (or GND) to +Vcc, with no intermediate values. Two states: 0 (-Vcc or GND) and 1 (+Vcc). In Digital and Analog I/O there is self insulation, so it is possible to connect them using a different power supply from the 24V one.

The Touchberry Panel provides 5 digital outputs  (from Q-0 to Q-4).

To configure the digital outputs, in the same way as the inputs, we will use the tests provided as follows:

pi@raspberrypi:~ $ ./test/digital/set-digital-output O0 1
pi@raspberrypi:~ $ ./test/digital/set-digital-output O0 0
pi@raspberrypi:~ $ ./test/digital/set-digital-output O1 1
pi@raspberrypi:~ $ ./test/digital/set-digital-output O1 0
pi@raspberrypi:~ $ ./test/digital/set-digital-output O2 1
pi@raspberrypi:~ $ ./test/digital/set-digital-output O2 0
pi@raspberrypi:~ $ ./test/digital/set-digital-output O3 1
pi@raspberrypi:~ $ ./test/digital/set-digital-output O3 0
pi@raspberrypi:~ $ ./test/digital/set-digital-output O4 1
pi@raspberrypi:~ $ ./test/digital/set-digital-output O4 0

This time the attributes of this test are: the output (O0..O4) and the state that we want to assign 0 for the LOW output and 1 for the HIGH output.

The Touchberry board contains test LEDs that allow us to see the configuration of the digital outputs.

Ethernet

Ethernet is the technology that is most commonly used in wired local area networks (LAN). A LAN is a network of computers and other electronic devices that covers a small area such as a room, office, or building. It is used in contrast to a wide area network (WAN) , which spans much larger geographical areas. Ethernet is a network protocol that controls how data is transmitted over a LAN. Technically it is referred to as the IEEE 802.3 protocol. The protocol has evolved and improved over time to transfer data at the speed of a gigabit per second.

*IMPORTANT: Make sure that your PLC is powered (12-24Vdc). Just with USB is insufficient power to power up the Ethernet communication.

Used pins:
For Ethernet communication with eth0 interface, there aren't any Raspberry Pi used pins.
Ethernet hardware configuration must be plug and play.

You can maintain a simple connection with the NETCAT tool with the following commands:

nc -l port (server)
nc server_ip port (client)

For instance:

Touchberry: nc -l 1234
Other PLC: nc 10.42.0.114 1234

Or you can create some slightly more complex code and create more complex automations depending on the functions you want to add.

WI-FI/BLUETOOTH

Wi-Fi is one of the most important technological developments of the modern age. Similar to other wireless connection types, like Bluetooth, it's a radio transmission technology that's built upon a set of standards to allow high-speed and secure communications between a wide variety of digital devices, access points and hardware. It makes it possible for Wi-Fi capable devices to access the internet without the need for restrictive wires. It can operate over short and long distances, be locked down and secured, or open and free, so it's incredibly versatile and easy to use.

Bluetooth is a another wireless technology standard. Bluetooth was developed as a way to exchange data over a short range. Operates in the 2400-2483.5 MHz range within the ISM 2.4 GHz frequency band. Data is split into packets and exchange through one of 79 designed Bluetooth channels (each of which have 1 MHz in bandwidth).

All products of the Raspberry Pi family incorporate WiFi/Bluetooth connection.

To setup Wi-Fi in the Raspberry PLC, you can follow this guide.

And if you want to know how to use Bluetooth to, for example, communicate the Raspberry PLC with an Android Phone, you can follow this guide.

I2C

I2C is a synchronous protocol that only uses 3 cables, one for the clock (SCL) and one for the data (SDA) and ground (GND). This means that the master and the slave send data through the same cable, which is controlled by the master, who creates the clock signal. I2C uses addressing to select slaves.

I2C is a serial communications bus. The speed is 100 kbit/s in standard mode, but also allows speeds of 3.4 Mbit/s. It is a very used bus in the industry, mainly to communicate microcontrollers and their peripherals in integrated systems, or to communicate integrated circuits that reside in a same PCB.

Example of use

To send an I2C message in a Linux environment, you can use the i2c-tools package, which provides the i2cset and i2cget commands.
These commands allow you to write data to an I2C device or read data from an I2C device, respectively.

Here's an example of how you can use i2cset to send an I2C message:

i2cset -y <bus_number> <device_address> <register_address> <value> [b]

• <bus_number>: The I2C bus number (e.g., 1 for /dev/i2c-1).
• <device_address>: The I2C address of the target device.
• <register_address>: The register address where you want to write data.
• <value>: The value you want to write to the specified register.
• [b]: Optional parameter indicating that the value is in byte format.

For example, to write the value 0x45 to register 0x02 of an I2C device with address 0x50 on bus 1, you would run:

i2cset -y 1 0x50 0x02 0x45

Keep in mind that the actual bus number, device address, register address, and data value will depend on your specific hardware and requirements.
Additionally, you may need to ensure that the I2C kernel modules are loaded (i2c-dev and the driver specific to your hardware). You can use the lsmod command to check if these modules are loaded.

lsmod | grep i2c

Here's an example of how you can use i2cget to read data from an I2C device:

i2cget -y 1 0x50 0x02

This command reads a byte from the specified register address (0x02) of the I2C device with address 0x50 on bus 1. The output will be the value read from the register.

SPI

SPI is a synchronous communication protocol bus that has a master-slave architecture. Slave devices cannot initiate communication, nor exchange data with each other directly. Only the master can select to which slave will communicate with through the SS (slave select) pin.

Example of use

To use SPI communications we recommend using the spidev library.

pip install spidev

Here you can see a simple example in python with which we can communicate using this protocol.

import spidev

# Initialize SPI
spi = spidev.SpiDev()
spi.open(0, 0) # The arguments (bus, device) depend on your setup

# Configure SPI settings
spi.max_speed_hz = 1000000  # Set the SPI speed (Hz)
spi.mode = 0                # Set the SPI mode (consult your device's datasheet)

# Prepare your data to be sent
data_to_send = [0x01, 0x02, 0x03]  # Replace with your actual data

# Send the SPI message
received_data = spi.xfer2(data_to_send)

# Close the SPI connection
spi.close()

# Process the received data if needed
print("Received Data:", received_data)

This Python code uses the spidev library to establish an SPI connection, send data, and receive a response from an SPI device.

RS-485

 RS-485, also known as TIA-485(-A), EIA-485, is a standard defining the electrical characteristics of drivers and receivers for use in serial communications systems. The electrical signaling is balanced, and multi-point systems are supported.

Example of use

RS-485, on this device, can be configured as Half Duplex or Full Duplex. Below we will see an example of each one.

First of all, to use this communication, some prior configurations must be made.

In order to configure the RE and DE:

echo 27 > /sys/class/gpio/export
echo 17 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio27/direction
echo out > /sys/class/gpio/gpio17/direction

The baudrate is very important in serial communications and is configured as follows:

stty 115200 -F /dev/ttyS0 raw -echo

In this case we have set it to 115200, but it can be varied according to your needs. With this we can begin.

Half Duplex:

Configuration of DE and RE for the use of RS-485 in Half duplex.

• For receptions:
  

echo 0 > /sys/class/gpio/gpio17/value
echo 0 > /sys/class/gpio/gpio27/value

Then, to see the data we are receiving, with the command:

cat /dev/ttyS0

• For transmissions:
  

echo 0 > /sys/class/gpio/gpio17/value
echo 1 > /sys/class/gpio/gpio27/value

So, we can send messages, for example with:

echo MESSAGE > /dev/ttyS0

Full Duplex:

Configuration of DE and RE in Full duplex:

echo 0 > /sys/class/gpio/gpio17/value
echo 1 > /sys/class/gpio/gpio27/value

Then you are ready to use RS-485 in your projects.

RS-232/TTL

 RS-232, also known as TIA-232-F, EIA-232-F, or V.24, is a standard for serial communication transmission of data. It specifies the voltage levels, signal timing, and data protocol for communication between devices.

TTL, or Transistor-Transistor Logic, is a digital logic family that uses transistor circuits to implement logic functions. In the context of serial communications, TTL refers to the voltage levels used to represent binary data. TTL levels typically range from 0 to 5 volts, with high voltages representing logic 1 and low voltages representing logic 0.

Example of use

Below we provide an example applicable to RS-232 and TTL, setting the baud rate to 115200, for example, with the following command:

stty 115200 -F /dev/ttyS0 raw -echo

Therefore, we send a message as follows:

echo -ne Hello > /dev/ttyS0

And we will receive through the port by executing:

cat /dev/ttyS0

UPS SHIELD

All Raspberry PLC Family devices include the UPS Shield. It is a Plug & Play UPS Smart Shield that provides 5 seconds of electricity in front of a power supply cut off. This extra time of electricity provides that the Raspberry follow a correct Shut Down process, avoiding any SD corruption issue. The recharge time of the UPS is less than 1 minute, and the reconnecting time is less that 20 seconds.
If you want to execute specific commands during an UPS shutdown, you can edit the "/etc/rpishutdown/hooks/pre-poweroff" file and put them in there. You may also need to give the file execution permissions with the "sudo chmod ugo+x /etc/rpishutdown/hooks/pre-poweroff " command.

Hardware Configuration

*IMPORTANT: Make sure that your Ethernet PLC is powered (12-24Vdc) and has the UPS Shield correctly mounted .

Switch configuration:
The Raspberry PLC UPS Shield hasn't any switch that affects it, it is always enabled. You only need to have it connected for at least 1 minute, to allow the super capacitors in the shield to recharge at boot.

Software Configuration

*IMPORTANT: Make sure that you have followed correctly the OS installation guide.

Software Configuration:
If you followed correctly the OS installation guide, the UPS Shield will automatically work when needed.

Capacitive Panel

Capacitive touch panels are often considered superior to resistive ones for several reasons:

1. Higher Sensitivity: Capacitive panels are more sensitive to touch, allowing for more accurate and responsive touch detection, even with light touches.
2. Multi-touch Capability: Capacitive panels support multi-touch gestures, such as pinch-to-zoom and swipe, making them suitable for devices like smartphones and tablets.
3. Better Display Clarity: Capacitive panels do not require additional layers over the screen, improving visual clarity and light transmission compared to resistive panels.
4. Durability: Capacitive panels are generally more durable than resistive ones, which can wear out over time, especially when touched with sharp objects.
5. Faster Response Time: Capacitive panels exhibit quicker response times, contributing to a smoother user experience in devices like smartphones and tablets.
6. Lower Pressure Requirement: Capacitive panels require less pressure to register a touch, enhancing user comfort compared to resistive panels.
7. Longer Lifespan: Capacitive panels typically have a longer lifespan as they are not subject to the mechanical wear associated with the physical pressure applied to resistive panels.

RTC (UPS SHIELD)

The UPS Shield contains a RTC DS3231 integrated circuit communicating via I2C-bus with the Raspberry Pi.The term real-time clock is used to avoid confusion with ordinary hardware clocks which are only signals that govern digital electronics, and do not count time in human units. RTC should not be confused with real-time computing, which shares the acronym but does not directly relate to time of day.

Although keeping time can be done without an RTC, using one has its benefits:

• Low power consumption (important when running from alternate power).
• Frees the main system for time-critical tasks.
• Sometimes more accurate than other methods.

There is a 3.3V lithium coin cell battery supplying the RTC, we recommend using the CR2032 battery. The Raspberry Pi RTC Modules is based on the DS3231 chip. The DS3231 serial real-time clock is a low-power, full binary-coded decimal  (BCD) clock/calendar. Address and data are transferred serially through I2C. The clock/calendar provides seconds, minutes, hours, day, date, month, and year information. The end of the month date is automatically adjusted for months with fewer than 31 days, including corrections for leap year. The clock operates in either the 24-hour or 12-hour format with AM/PM indicator. The DS3231 has a built-in power-sense circuit that detects power failures and automatically switches to the backup supply. Timekeeping operation continues while the part operates from the backup supply.

Hardware Configuration

*IMPORTANT: Make sure that your Ethernet PLC is powered (12-24Vdc) and has the UPS Shield correctly mounted .

Software Configuration

*IMPORTANT: Make sure that you have followed correctly the OS installation guide.

Software Configuration:
Once the hardware configuration is done, it's possible to proceed with the software configuration and also its usage. You can check this guide to do so.

Improvements in new versions

The new versions of Touchberry have a series of additions that improve this PLC Screen:

• Isolation between I/O pins and communication pins
• An additional USB is released
• Possibility of adding a click board
• Improved RS485 and I2C connector isolation

• Such as thermal insulation, eliminating the need to use a fan, which improves the size, the weight and the noise of the product.