Initial Installation
GETTING STARTED
First of all, the Raspberry Pi PLC will need an operative system to start running. Although you can use any GNU/Linux distribution, we recommend you to stick into Raspberry Pi OS, which is the official supported OS for the Raspberry board.
To install an OS onto the Raspberry Pi, please refer this guide.
If you have followed the guide accurately, you can access the Raspberry PLC either through a screen and keyboard or via SSH using the Ethernet port. In case you prefer the latter method, you can follow this guide on how to access the PLC via SSH.
PROGRAMMING THE PLC
The primary benefit of using the Raspberry Pi PLC is that it is compatible with any Integrated Development Environment (IDE) that works with the compatible programming languages. This can be accomplished by either accessing an IDE installed on the PLC via X-forwarding through "ssh -X", or using an IDE installed on your computer, and then transferring the files through SFTP/FTP.
Although a variety of programming languages can be used, we advise utilizing Python, C++, and Node-RED as these are our officially supported languages.
PYTHON
Python 3.9.2 is already pre-installed in the Raspberry Pi OS, and therefore, doesn't require any additional installation.
However, to access the PLC's Input/Output (I/O) and interrupts, you will need to install both the rpiplc and rpiplc-python3 libraries, which should already be installed if you followed the guide to install the OS.
Install C++ library for Raspberry Pi PLC (dependency for the Python library):
rpiplc-library Installation guide
Install Python library for Raspberry PLC:
rpiplc-python3-library Installation guide
C++
The GCC toolchain is pre-installed with the Raspberry Pi OS. Therefore, there is no need for any additional installation to use C++.
However, to utilize the PLC's I/O and interrupts, you will require the rpiplc libraries, which should already be installed if you followed the guide to install the OS.
Install C++ library for Raspberry Pi PLC (dependency for the Python library):
rpiplc-library Installation guide
Node-RED
Node-RED is a browser-based flow editor that enables the graphical programming of hardware devices, APIs, and online services. It is constructed on top of Node.js, which allows for the full use of its event-driven, non-blocking model.
Unlike Python or C++, Node-RED must be manually installed. To do so, you can either follow the last step of the OS installation guide or refer to the User Guide.
POWER SUPPLY
All Raspberry Pi based industrial PLC’s (programmable logic controllers) can be powered between 12-24V. The Raspberry Pi family has a consumption between -mA and +mA. So, the recommended power supply is 2A or higher. Any Industrial power supply will be a good choice to power supply them.
REMEMBER: Our units are designed to be powered between 12-24V. Just powering them with the USB, the unit will not be able to perform their features.
If for some reason you would like to use a power supply lower that is less than 3A contact with Industrial Shields technical support to ensure that your system will complete your functionalities without any power issue.
In the next image you can see a simple diagram about how to connect a power supply to any Industrial Shields unit.
SWITCH
Our boards have the nomenclature showed below:
The communication board (A zone) is shared with all Raspberry Pi family, and it doesn't have any switches available.
B Zone Analog:
| SWITCH | OFF | ON |
|
NC
|
- |
- |
|
Q0.7
|
A0.7 | Q0.7 |
|
Q0.6
|
A0.6 | Q0.6 |
|
Q0.5
|
A0.5 |
Q0.5
|
C Zone Analog:
| SWITCH | OFF | ON |
| NC | - | - |
| Q1.7 | Q1.7 | A1.7 |
| Q1.6 | Q1.6 | A1.6 |
| Q1.5 | Q1.5 |
A1.5
|
D Zone Analog:
| SWITCH | OFF | ON |
| NC | - | - |
| Q2.7 | Q2.7 | A2.7 |
| Q2.6 | Q2.6 | A2.6 |
| Q2.5 | Q2.5 |
A2.5
|
If the Analog Shield's switch is set to ON, it will function solely as a Digital Output. Conversely, if it is set to OFF, it can only function as an Analog Output.
To use a Digital Output, the pin must be set to ON, and the pin representing the desired digital output will be denoted by QX.X, where X can be any number from the tables above.
To use an Analog Output, the pin must be set to OFF, and the pin representing the desired analog output will be denoted by AX.X, where X can be any number from the tables above.
Inputs & Outputs
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.
Inputs: (18x) Analog Inputs (0-10Vdc) / Digital (5-24Vdc) configurable by software.
To know more about analog inputs...
TYPICAL CONNECTIONS:
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.
Inputs: (39x) Digital inputs (5-24Vdc) configurable by software, of which (21x) are Isolated Digital (5-24Vdc).
To know more about digital inputs...
TYPICAL CONNECTIONS:
-
Digital isolated inputs:
-
Digital non-isolated inputs:
INTERRUPT INPUTS
Interrupt Service Rutine: A mechanism that allows a function to be associated with the occurrence of a particular event. When the event occurs, the processor exits immediately from the normal flow of the program and runs the associated ISR function ignoring any other task
| Interrupt | Raspberry Pi Pin | Raspberry PLC Pin |
| INT0 | GPIO13 |
I0.5/INT0 |
| INT1 | GPIO12 |
I0.6/INT1 |
| INT4 | GPIO5 | I1.6/INT4 |
| INT5 | GPIO27 | I1.5/INT5 |
| INT2 | GPIO4 | I2.6/INT2 |
| INT3 | GPIO26 | I2.5/INT3 |
To know more about interrupts...
TYPICAL CONNECTIONS:
If you want to see an example to know how to program ISRs with Python, you can check this example.
ANALOG OUTPUTS
In analog outputs, the voltage difference between -Vcc (ground) and +Vcc can vary across a wide range of values. An analog output's value is determined by a digital value of N-bits. 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.
Outputs: (9x) Analog Outputs (0-10Vdc) / Digital Outputs (5-24Vdc).
To know more about analog outputs...
TYPICAL CONNECTIONS:
DIGITAL OUTPUTS
In digital outputs, 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. An analog output's value is determined by a digital value of LOW (0) or HIGH (1). 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.
Outputs: (24x) Isolated Digital Outputs (5-24Vdc), 9 of which are 5-24V PWM and 3 of which are 5V PWM, all configurable by software.
To know more about digital outputs...
TYPICAL CONNECTIONS:
PWM OUTPUTS
Pulse Width Modulation. It's a technique that consists in activating a digital output for a while and keep it off for the rest. The average output voltage, over time, will be equal to the desired analogue value. The frequency between pulses is maintained, the only thing that changes in time is the pulse's width. Attention: A PWM Output gives a Vcc value during a certain time. So, during a percent time is +Vcc and the rest of time is -Vcc (or GND). If we directly supply this signal to a device that accepts less than +Vcc, we can damage it.
You have to keep in mind that:
- Q0.5, Q0.6 and Q0.7 Digital/PWM out also as A0.5, A0.6 and A0.7 Analog out.
- Q1.5, Q1.6 and Q1.7 Digital/PWM out also as A1.5, A1.6 and A1.7 Analog out.
- Q2.5, Q2.6 and Q2.7 Digital/PWM out also as A2.5, A2.6 and A2.7 Analog out.
To use the Digital/PWM configuration pins (QX.X), you have to turn On the switch of the zone's pin:
TYPICAL CONNECTIONS:
If you want to see an example to know how to interact with PWMs with Bash or C++, you can check this examples.
Communications
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.
Our Raspberry Pi family incorporates both an integrated W5500 IC and the own Ethernet port of the Raspberry.
W5500 is a Hardwired TCP/IP embedded Ethernet controller that provides easier Internet connection to embedded systems. This chip enables users to have Internet connectivity in their applications by using the single chip in which a TCP/IP stack, 10/100 Ethernet MAC and PHY are embedded. The W5500 chip embeds the 32Kb internal memory buffer for the Ethernet packet processing.
Hardware
*IMPORTANT: Make sure that your PLC is powered (12-24Vdc). Just with USB is insufficient power to power up the Ethernet communication.
Switch configuration:
For the Ethernet communication protocol there isn’t any switch that affects it, so it doesn't matter the configuration of the switches to implement Ethernet communication.
Used pins:
For Ethernet communication with eth0 interface, there aren't any Raspberry Pi used pins.
However, for Ethernet communication with eth1 interface, the used Raspberry Pi pin is GPIO7, which is connected and already internally assembled to the W5500 Ethernet controller. You can easily access to the Ethernet port, as it is located at the top of the communications layer.
Ethernet hardware configuration must be plug and play.
Software
*IMPORTANT: Make sure that you have followed correctly the OS installation guide.
Software Configuration:
Once the hardware configuration is done, it is possible to use the Ethernet port as you would do with any other Linux computer. There isn't any need to install extra libraries to begin with it.
SERIAL TTL
Serial TTL is a protocol for serial communication that is used in many embedded microcontrollers for asynchronous communication. A serial port sends the data in a bit by bit sequence, and because it is asynchronous communication, there isn't any clock signal that synchronizes the data. The UART ("Universal Asynchronous receiver-transmitter") circuitry handles the synchronization through start and stop bits, supposing that both devices are working at the same baud speed.
Being TTL means that the used logic levels are '0' (GND) or '1' (Vcc, in this case 3.3V). Unlike RS-485 or RS-232, it doesn't use voltage differences and it's full duplex by default (TX and RX in separated cables + GND).
The Raspberry PLC family has only one Serial port in pins RX/TX (GPIO15 and GPIO14 respectively). It can be accessed by configuring it with the stty command or through Serial libraries for programming languages like C++ (iostream, standard library) or Python (pyserial).
Hardware
*IMPORTANT: Make sure that your PLC is powered (12-24Vdc).
Switch configuration:
For the Serial communication protocol there isn’t any switch that affects it, so it doesn't matter the configuration of the switches to implement Serial communication.
Used pins:
For Serial communication protocol, the used pins are the ones corresponding to the Raspberry's serial ports (GPIO14/TX and GPIO15/RX).
Software
*IMPORTANT: Make sure that you have followed correctly the OS installation guide.
Software configuration:
For the serial communication there isn’t any switch that affects it, so it doesn't matter the configuration of the switches to implement Serial communication.
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.
Hardware
*IMPORTANT: Make sure that your PLC is powered (12-24Vdc).
Switch configuration:
To achieve I2C communication there isn't any switch that affects it, it is always enabled. So it does not matter the configuration of the switches to implement I2C communication.
Used pins:
For I2C communication protocol the defined pins are the ones corresponding to the Raspberry Pi (GPIO2 for SDA and GPIO3 for SCL).
Software
*IMPORTANT: Make sure that you have followed correctly the OS installation guide.
Software configuration:
First you will need some libraries to get I2C working in the Raspberry PLC:
sudo apt-get install -y python3-pip
pip3 install adafruit-blinka
Once these packages are installed, it is possible to start using I2C with Python. You can follow this guide to learn how you can program an I2C scanner, a program that searches for available devices in the bus.
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.
SPI1 is internally assembled with the RS-485 transmitter and receiver. And SPI0, which is available through the Raspberry PLC pins, is shared with Ethernet W5500 IC. The GPIO8 pin acts as the SS pin for an external device. All these pins must work at 3.3V.
Hardware
*IMPORTANT: Make sure that your PLC is powered (12-24Vdc).
Switch configuration:
To achieve SPI communication there isn't any switch that affects it, it is always enabled. So it doesn't matter the configuration of the switches to implement SPI communication.
Used pins:
For SPI communication protocol the defined Raspberry Pi pins are showed in the chart below:
| SPI |
Raspberry PLC
|
Raspberry Pi pinout
|
| MOSI | MOSI |
GPIO10 |
| MISO | MISO |
GPIO9 |
| SCLK | SCK |
GPIO11 |
| SS0 | GPIO8 |
GPIO8 |
| SS1 |
Internally assembled
|
GPIO7 |
Software
*IMPORTANT: Make sure that you have followed correctly the OS installation guide.
Software configuration:
First you will need some libraries to get SPI working in the Raspberry PLC:
sudo apt-get install -y python3-pipOnce these packages are installed, it is possible to start using SPI with Python. You can follow this guide to learn how you can use two Raspberry PLCs to communicate each other.
pip3 install spidev adafruit-blinka
Special Functions
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.