Getting Started Guide

This page will guide you on how to set up the FibStack PiSwitcher Plus board. The page includes hardware and software installation, recommendations, limitations, and code examples. As we and the Open Source community improve the design, the content of this guide and the reference material may change as well.

Hardware Installation

WARNING. Hazard of severe electrical shock or burn when using High Voltage/Current applications. Obey High Voltage/Current safety procedures. FibStack is not responsible for any damage or injury that occurs from improper use of the PiSwitcher Plus board.

IMPORTANT

Disconnect all power sources before installing or servicing the board

Verify all the connections before turning any power source on

Provide the power through the Raspberry Pi board. The GND and +5V pins on the PiSwitcher Plus board are reference voltage for the ADC channels.

DO NOT USE voltage and current values outside the specified range specified.

Use the High Voltage/Current applications at your own risk.

Installation Steps

Disconnect the Raspberry Pi board from the power supply
We recommend attaching M2.5 16mm standoffs to prevent PiSwitcher Plus board contacts from touching Raspberry Pi board components.
Attach the PiSwitcher Plus board to the Raspberry Pi board
Connect the wires to the relay switches and ADC channels according to your project schematics. To avoid any damage or injury, make sure there is no current running through the wires while connecting
Connect the power source to the Raspberry Pi board. The red LED on the PiSwitcher board should light up.

The default FibStack PiSwitcher Plus board I2C address is 0X50. If you want to add another board that uses the same default address, make sure you change the I2C address of the current board. You can easily change the I2C address using the Dashboard or the FibStack CLI utility.

Relay Switches

The FibStack PiSwitcher Plus board has four relay switches. The screw terminal block has three contacts for each relay. COM - Common, NC - Normal Close, and NO - Normal Open. When energizing a relay’s coil, the COM contact will disconnect from NC and connect to NO, and the corresponding LED indicator will light up. We recommend using the J0971C relay model. The maximum switching alternative current/voltage for this relay is 10A/250VAC, and maximum switching continuous current/voltage is 5A/30VDC.

Relay Switch

When all relay switches and LED indicators are on, the PiSwitcher Plus board will consume about 0.5A (2.5W) more on top of what the Raspberry Pi board consumes. You may get a low voltage warning or unpredictable behavior if the power supply doesn’t provide enough current. When you stack multiple boards together, make sure your power source provides enough current.

ADC Channels

Warning The +5V and GND pins on the PiSwitcher Plus board are a reference voltage for the ADC channels. The devices connected to the ADC channel should not consume power from the +5V pin.

The FibStack PiSwitcher Plus board also has four 12-bit ADC channels. The reference voltage is the board power source voltage coming from the Raspberry Pi board, so the signal connected to the ADC channel should be between 0 - 5V range. Between 0 and 4097 is the converted value. Warning: the power source voltage coming from the Raspberry Pi board may fluctuate and affect the ADC conversion results. If you leave the ADC channel pin unconnected or ungrounded, the ADC converter will convert the noise to that pin.

ADC Channels

The ATTiny824 microcontroller converts the signal on each channel sequentially. And the I2C interface speed may also limit the rate you receive the conversion results. So the board is not appropriate for high-frequency applications such as converting an audio signal.

Software installation

IMPORTANT: Currently, the FibStack Software package supports only Raspberry Pi OS.

To control the PiSwitcher board, you need to download and install the FibStack software package. The software package is available as a self-extractable script and as a *.tar.gz archive.

File	Size	Release
fibstack_package-1.0.3.run	103KB	March-15, 2023
fibstack_package-1.0.3.tar.gz	84KB	March-15, 2023

Download one of the installation packages and follow the instructions below to install.

Self-extractable file installation

Step 1: Make sure that the *.run script has executable permission. Run ls -l in the folder where the file is.

$ ls -l
total 104
-rw-r--r-- 1 pi pi 105522 Nov 11 06:53 fibstack_package.run

Step 2: Use the chmod command to set the executable permission on the file if not set.

$ chmod +x fibstack_package.run
$ ls -l
total 104
-rwxr-xr-x 1 pi pi 105522 Nov 11 06:53 fibstack_package.run

Step 3: Run the installation file as a sudoer user. Otherwise, the software package will not install.

sudo ./fibstack_package.run

*.tar.gz file installation

Step 1: Unarchive the content of the *.tar archive.

tar -xf fibstack_package.tar.gz

Step 2: Run the install.sh file as a sudoer.

sudo ./install.sh

The installation process will install the FibStack Dashboard, FibStack CLI tool, programming libraries and enable the I2C interface if not enabled. If the installation was successful, you should be able to access the FibStack Dashboard at http://localhost:4545. The default I2C address is 0X50. You can change it using the FibStack Dashboard or FibStack CLI tool.

Code Examples

Before we dive into code examples, I want to take a few minutes and explain how the board works.

The FibStack Switcher Plus board contains eight devices: four relay switches and four 12-bit ADC channels. Each device on the board has an ID assigned to it.

The Relay Switch device is a Read/Write device, and it can have two potential values: 0 and 1 (or FALSE and TRUE, or OFF or ON).
0 - means default state, when no voltage applies to the relay coil, and the COM contact connects to NC contact.
1 - means connected state, the chip on the board energizes the relay’s coil, the COM contact connects to NO, and the LED indicator is lit up. The ADC device is Read-Only, and its value represents the result of the ADC conversion. The ADC device converts the signal applied to the corresponding ADC channel pin.

The FibStack Programming API allows to:

query all FibStack boards attached to the Raspberry Pi
get the values of each device on the board
set the value for the Read/Write devices

The code examples below assume you have the PiSwitcher Plus board attached to the Raspberry Pi and install the software package.

Below are C and Python program examples that turn on the relay switch 1 when the signal on the ADC device (channel 1) is above the half voltage reference. When the signal drops below the half voltage reference, the program turns off the Relay Switch 1.

Here is a sample schematic for the code sample below. It uses a potentiometer to change the signal value on the ADC1 pin. Based on the signal value, the example below will turn the light bulb on and off.

Example Schematic

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <signal.h>
#include <fibstack.h>

/**
 * The maximum value for ADC conversion is 4096, half of this is 2048
 */
#define HALF_ADC_VALUE 2048

static struct fibstack_context *context = NULL;

/**
 * Signal Handler for SIGINT
 */
void sigint_handler(int sig_num)
{
    // The user initiated external interrupt, usually by pressing CTRL+C
    // Before exit, deallocate the context structure.
    if(context != NULL)
    {
        fibstack_context_free(context);
    }
    exit(0);
}

int main()
{
    context = fibstack_context_new();
    int board_number = fibstack_context_get_board_number(context);

    signal(SIGINT, sigint_handler);

    if(board_number < 1)
    {
        return 1; // Error, no board connected
    }

    struct fibstack_board *board = fibstack_context_get_board_by_index(context, 0);

    while(1)
    {
        fibstack_board_update(board);
        bool is_relay_switch_0_on = fibstack_board_get_boolean(board, 0);
        int adc_ch_0_value = fibstack_board_get_integer(board, 4);

        if(!is_relay_switch_0_on && adc_ch_0_value > HALF_ADC_VALUE)
        {
            fibstack_board_set_boolean(board, 0, true);
        }
        else if (is_relay_switch_0_on && adc_ch_0_value <= HALF_ADC_VALUE)
        {
            fibstack_board_set_boolean(board, 0, false);
        }

        sleep(1);
    }

    return 0;
}

When compiling the above C code, you need to specify the libfibstack library.

gcc mian.c -o main -lfibstack

Line 17: When the user presses the CTRL+C, it sends the program interrupt signal, this invokes the signal handler, and we have to deallocate the memory for the context structure (line 23).

Line 30: Initialize the context structure, which contains information about all connected FibStack boards.

Line 33: Since we are running an infinite loop, the user will interrupt the program execution by pressing CTRL+C, so we register a signal handler to free the context variable.

Line 35: Check if there is at least one FibStack board connected.

Line 40: Get the board structure

Line 44: Query the board to update all the devices’ values.

Line 45: Get the Relay Switch status.

Line 46: Get the ADC conversion value.

Line 48: If the Relay Switch is off, and the signal value is greater than the half voltage reference, turn on the Relay Switch.

Line 52: If the Relay Switch is on, and the signal value is less than the half voltage reference, turn off the Relay Switch.

Line 57: Wait one second.

IMPORTANT: The relay models may not be for switching electrical currents many times per second. Doing so may damage the relay device irreversibly. Consult the manufacturer datasheet.

The Software Package supports Python 3.7+.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import time
from fibstacklibpy import FibstackContext

half_adc_value = 2048
context = FibstackContext()
total_boards = context.get_total_boards()

if total_boards > 0:
    # Assuming at least one Fibstack Board is connected
    board = context.get_board_by_index(0)
    
    while True:
        # When calling get_device() method, internally it will call 
        # update() method to get the current value from the board
        switch_device0 = board.get_device(0)
        adc_device0 = board.get_device(4)
        
        print("Relay Switch: {0},  ADC Value: {1}".format(switch_device0.value, adc_device0.value))
        
        if not switch_device0.value and adc_device0.value > half_adc_value:
            board.set_device_value(switch_device0.id, True)
        elif switch_device0.value and adc_device0.value <= half_adc_value:
            board.set_device_value(switch_device0.id, False)
        
        time.sleep(1)

Line 5: Initialize the context object.

Line 6: Get the total number of FibStack boards connected.

Line 8: Check if there is at least one FibStack board connected.

Line 10: Get the board object.

Line 15: Get the first relay device.

Line 16: Get the first ADC device.

Line 20: If the Relay Switch is off, and the signal value is greater than the half voltage reference, turn on the Relay Switch.

Line 22: If the Relay Switch is on, and the signal value is less than the half voltage reference, turn off the Relay Switch.

Line 25: Wait one second.

IMPORTANT: The relay models may not be for switching electrical currents many times per second. Doing so may damage the relay device irreversibly. Consult the manufacturer datasheet.

If you run this program in the command line, it will run in an infinite loop until the user interrupts with CTRL+C command.