SPIT_GPIO

Author: Hagi Blickle   www.liveshowsoftware.de

SPIT_GPIO is the setup software for the SPIT_GPIO board extension of the Raspberry Pi. You can use the Raspberry Pi 4 B or the Raspberry Pi 3 B+.

The SPIT_GPIO software also regulates the control of the board, therefore the SPIT_GPIO software must run permanently on the Raspberry Pi.



The outputs of the board can be accessed via a external control software (e.g. liveSHOW software) and/or by triggering independent actions.


On the SPIT_GPIO board there are different components and connections:

Security notice:

All actions are shut down to zero (finished) when:
Please keep this in mind when connecting props or anything else to the Raspberry Pi!

You should also be careful not to control dangerous objects with the Raspberry Pi and that no dangerous objects are connected during programming and testing.
(Example: if you are controlling pyrotechnics with the relays, you must ensure that you comply with the legal requirements and that no effect is armed during the programming and test phase).
This also applies to any other technology you want to control with this software.
All programming must be tested in a safe environment before use!

Disclaimer:

The developer assumes no liability for damage caused by improper operation.
The software has been carefully tested. Should there be any errors, these can be reported to the developer.
Claims for damages by the customer are excluded, unless otherwise provided for the following reasons.
This also applies to the representative and vicarious agents of the provider, if the customer makes claims for damages against them.
Excluded are claims for damages of the customer due to injury to life, body, health or essential contractual obligations,
which must necessarily be fulfilled in order to achieve the contractual objective.
Likewise this does not apply to claims for damages after grossly negligent or intentional breach of duty of the provider or
his legal representative or vicarious agent.


Network connection with the Raspberry Pi:

In order for the SPIT_GPIO board outputs to be accessed by a external control software (e.g. liveSHOW software), the Raspberry Pi and the computer running the external control software (liveSHOW software) must be connected via network.
If both are on the same network, the SPIT_GPIO software will automatically find the external control software (liveSHOWsoftware) and establish a connection.

a) via WLAN

Both the computer running the liveSHOW software and the Raspberry Pi must be connected to the same WLAN access point.
The Raspberry Pi can be connected to an access point by clicking on the network symbol with the left mouse button.


A list with all access points that have just been detected opens. A click on an access point establishes a network connection. If a connection has never been established to the access point, a window opens in which the WLAN password of the access point must be entered.

ATTENTION: Do not use the access point at home, but always use the access point that you also use at the show. The Raspberry Pi will always connect to the access point it was last connected to after a restart.
Note: It is best to get a hardware access point that has DHCP built in. Such an access point can assign network IP addresses and there is no need to enter static network addresses on the Raspberry Pi.

b) via LAN cable

A LAN cable must be connected to the Rasbperry Pi, the other side of the LAN cable can be connected to the computer running the liveSHOW software or a network hub/switch.
The network icon changes  

The Status Bar

The connection status is displayed in the upper line

If there is a connection to a SPIT server (liveSHOWsoftware), the square is displayed in green and the current computer name and project name of the SPIT server is shown.
 

If there is no connection, the square is displayed in red and no project name is shown:
  


opens a help window.

The settings

Note: Changes must be saved, otherwise they have no effect!

With 
the changes are saved.
Press 
to discard the changes. An exception is the setting of the elements of a standalone action, these cannot be discarded.

Note: The settings are saved on the RaspberryPi in the folder /home/pi/.SPIT_GPIO. The basic settings are stored in the file settings(x).ini (x) stands for the hardware number of the plug-in board.
All project-dependent settings are saved in files whose name corresponds to the name of the loaded project of the external control software (e.g. liveSHOWsoftware) - see below: Setting the hardware... - Input.

With 
the settings files can be exported to another folder, e.g. to a USB stick.
With 
the settings files can be imported from an (export) folder.

Prefix

A short text can be entered at the top of the settings window, which precedes all other names, so that the names can be distinguished in the external control software if several Raspberry Pi are used.



Short explanation: You can use several Raspberry Pi with SPIT_GPIO boards. The first time you start the SPIT_GPIO software on a Raspberry Pi, an internal unique ID is assigned once for each component (possible triggers).
Thus the triggers are different from two Raspberry Pi, even if they have the same name.
The triggers are not distinguished by the name, but by the internal ID.
In the control software (liveSHOWsoftware) several triggers may appear, which may have the same name, but different IDs.
To be able to distinguish them better in the external control software (liveSHOWsoftware), you must change either the prefix or the names of the individual triggers in the SPIT_GPIO software (see also example liveSHOWsoftware at the end of the text).

By exporting the settings, the internal ID's are also exported. So you can save the settings to a new Raspberry Pi or to a new SD card by importing the exported settings. If you use more than one Raspberry Pi, you will need to make a separate export of each one as a backup. You should make sure that you do not run two Raspberry Pi with the same settings (imported backups), otherwise the internal IDs will exist several times.



Setting the hardware in-/outputs of the board:

All changes can be saved with 'Save'. With 'Cancel' the changes are discarded.

 Input

At the inputs (Input) e.g. push buttons can be connected. If the contacts of an input are connected or disconnected, a remote control command can be sent to the external control software (liveSHOWsoftware) and/or an independent action (standalone action) can be triggered
This allows the remote control of the external control software or the playback of standalone actions without a external control software.



'---' means that nothing is triggered.

a) connect 
In this case the set remote control command is sent when the contacts are connected (e.g. the connected button is pressed)
b) disconnet
In this case the set remote control command is sent when the contacts are disconnected (e.g. the connected button is released)

The Standalone Actions are explained below.

A remote control command can trigger an action (e.g. jump to the next scene) or change values (e.g. sound volume).

In the case of changing values, you can also set whether the value should be increased by 5% (+5%) or decreased by 5% (-5%).

It is not possible to enter values directly, only increasing or decreasing a value can be triggered.

Note: For the remote control commands to be listed, a connection to the external control software (e.g. liveSHOWsoftware) must exist.


When saving  , the remote control commands are always saved in a file that has the same name as the project name of the external control software (e.g. liveSHOWsoftware).
Thus the name of the project name of the external control software is decisive for it into which file the remote control commands are stored and loaded again!
You should choose the project name of the external control software carefully.

The location in the Raspberry Pi is
/home/pi/.SPIT_GPIO/

Example: If the external control software has the project name "Project1", a file /home/pi/.SPIT_GPIO/Project1 will be created when saving or overwritten, if it already exists.

If you create new projects very often, you can delete the no longer needed files (e.g. /home/pi/.SPIT_GPIO/Project1.ini) on the raspberry under the folder (/home/pi/.SPIT_GPIO).


If a project is loaded in the external control software, the SPIT_GPIO software on the Raspberry Pi tries to find a file that corresponds to the project name.
If a corresponding file is found, the remote control commands are loaded from this file.
If no corresponding file is found, e.g. because no settings have been saved for this project yet, only the project-independent remote control commands remain.

There are two types of remote control commands:

   1. project independent remote control commands
      These are commands that are always present, regardless of which project was loaded by the external control software (liveSHOWsoftware).
      In the case of the liveSHOWsoftware this is for example the command 'next scene' or the 'sound volume'.
   2. project dependent remote control commands:
      These are commands that only exist if a specific project has been loaded by the external control software.
      In the case of the liveSHOWsoftware this is for example the command 'start specific scene bridge' or 'start specific jingle'. If the liveSHOWsoftware loads another project, the scene bridge or jingle no longer exists.
      Project-dependent commands are shown with a '*' in front of the name.


Use the Test buttons to test the settings of the individual inputs.
The test button at 'connect' reacts on pressing the mouse button and starts the actions for connecting the input contacts.
The test button at 'disconnect' reacts to the release of the mouse button and starts the actions for disconnecting the input contacts.

Note: The Test buttons will work even without saving the settings first.
For the settings to be applied and the hardware input to work, the settings must first be saved.






Servo-Motor-Output



A servo motor can be controlled via the motor output of the board. The position (deflection) of the motor can be determined via the control software or via an item of a standalone action.


The maximum deflection of the motor can be entered at : Thus it is possible to set a limitation of the maximum deflection.
0.0 = zero position
0.5 = the motor is deflected by a maximum of 50%.
1.0 = normal full deflection
> 1.0 = the motor is overridden, this is allowed by some motors. If this value is set too high, the motor may not react or jitter!

Reasons for overriding:
Normally the maximum value is between 0.0 and 1.0. The motor should run from zero to full deflection.  Not all motors reach the mavimum deflection specified by the manufacturer.
Some motors have control electronics that do not comply with the actual norm and do not reach full deflection at a value of 1.0. In this case you can try to see if the motor reacts if you set a value higher than 1.0.
However, if a too high value is used, the motor will not react at this value. The maximum highest value can only be determined by trial and error, the value at which the motor still reacts should be used.
The behaviour of motors can be quite different, due to the cheap manufacturing process of some motors, even motors from the same charge can react differently.


A name ('Motor_1) can be assigned in the settings window, which is then also displayed in the control software with a prefix.

Interna: The pin number of the used pin on the Raspberry Pi is displayed, this is the WiringPi numbering.
If the SPIT_GPIO software is started with admin rights, the output is controlled by the hardware PWM, otherwise the motor is controlled by the software PWM and may jitter.

Please note that a servo motor may need a lot of current(A). When choosing a servo motor you should make sure to use a motor with as little current consumption as possible. The current power banks usually deliver 5V and a maximum of 2,5 A.
If your servomotor requires a different voltage or has a high power consumption, the servomotor must be supplied by an external power source. For this purpose, the negative connection of the board, the negative connector of the motor and the negative pole of the external power source must be connected. The positive connector of the motor is connected to the positive pole of the external power source. The data line is connected to the data connector of the board.





  Relays-Output



There are several relays on the SPIT_GPIO board.
A relay works like a switch, it can be switched on or off. When switched on, the contacts of the relay are connected.
In this way, a relay can be used to switch a different circuit.
Which voltage (V) and current (A) are allowed depends on the board. Please refer to the description of the hardware board.
In the settings window a name can be entered for each relay. 

Interna: For each relay the pin number of the used pin is shown on the Raspberry Pi, this is the WiringPi numbering.






 LED-Output



An LED (short LED stripes) can be connected to an LED output of the board. LED's can be dimmed (pulse width modulation PWM). The brightness of an LED (LED strip) can be controlled via the control software.
In the settings window a name can be specified for each LED output. This name is displayed in the control software with the prefix in front,
How many LEDs can be controlled by one LED_output depends on the hardware board and its power supply. If individual LEDs are connected, a resistor must be connected in series.
Please read the description of the hardware board!

Interna: For each LED output the pin number of the used pin is displayed on the Raspberry Pi, this is the WiringPi numbering.







 RC (Radio Control)



Radio commands can be sent via the 433 MHz RC transmitter of the board. These radio commands can be learned via the built-in 433MHz receiver.
So you can switch e.g. radio sockets or gadgets (magic devices, LED poi, etc) via the control software.

Note: Not all 433 MHz transmitters/receivers use a standardized protocol, there are also very individually built transmitters/receivers. Therefore you will not be able to recognize all radio commands.

With  a new RC command can be created.

Each RC command can be given a name, which is displayed in the control software with the prefix in front.

Basically there are three types of RC Komandos 
The text fields show some information about the learned radio command - see below,
 

In the text field  you can specify how often the radio command should be sent.
Some receivers only react if the radio command is sent several times, this must be tried out. Since sending a radio command takes some time and the RC transmitter cannot send any further radio commands during this time, the repetition should be as small as possible, but it must be high enough for the receiver to respond safely.
Learning  can be started by clicking on  (for learning) - see below.
With  the learned signal can be sent for test purposes.
With a click on  the respective RC command is deleted.

Note: If you have several remote controls for different devices and they all transmit on the 433 MHz frequency, it is impossible to press two remote controls simultaneously. The radio signals mix and nonsense comes out.
The SPIT_GPIO software does not send the radio signals at the same time, but quickly one after the other. So it is possible to send several radio signals pseudo-simultaneously, but if one radio signal takes a longer time, the other receivers may drop out.

Characteristics of radio sockets

Some radio socket receivers have a DIP switch with which the coding of the EM receiver can be set.
Some radio socket receivers must be trained once with the handheld transmitter. Depending on the design, the receivers retain this information even if they are disconnected from the power supply. However, there are also radio socket-outlet receivers that lose this information after some time and have to be trained again. Therefore you should always carry the handheld transmitter with you.

The learning of a radio command (SPIT_GPIO_Sniffer):

For this you need the handheld transmitter of your radio receiver.
With a click on  the SPIT_GPIO_Sniffer window opens. Here the reception of 433MHz signals is activated.



Hold your handheld transmitter very close to the circuit board and press the button of your handheld transmitter to be trained.

If data is received, the background of the message text changes to green:

If noisy data is received, e.g. because there is too much interference, the background changes to yellow:
   

If the background never turns green and you do not receive any values or the background changes often without you having pressed the handheld transmitter, there is a lot of interference in the environment.
If possible go to another place.

Stay on the remote control button until a stable sequence of digits or a list of sequences of digits is displayed.



Some wireless devices use a rolling code, in which case several sequences of digits are displayed:.



Note: If you release the button of the handheld transmitter and wait 2 seconds, you can start a new teach-in attempt.

The received data and parameters of the radio protocol can be transferred to the settings window with ..
In the settings windows you can test by clicking on  whether the receiver reacts to the learned command. If not, repeat the teach-in or increase the repeat value.
Note: Some radio transmitters/receivers cannot be read out correctly because the radio protocol is not listed in the software or a specially encrypted command is used.
For example car keys have a special encryption system, such a system cannot be taught!
Besides the 433 MHz radio system, there are also radio systems that transmit in a different radio frequency, these can also not be used here.
But usually a very high percentage of the 433 MHz radio systems on the market is recognized.


With  the values are transferred to the settings window, with  the recognized values are discarded, theSPIT_GPIO_Sniffer window is closed.

What can be done if the teach-in of a device does not work - no sequence of digits is displayed?

There are different causes if the teach-in does not work:
  1. You are too far away from the board with the handheld transmitter!
    Then the signals are too weak for the built-in receiver. Go very close to the circuit board and press the button on the handheld transmitter again.
  2. There are many interfering transmitters in the area!
    You can usually recognize this by the fact that 'Press Button on your RC transmitter' wriggles without the handheld transmitter being pressed.
    Look for a quieter environment - without many radio sources.
  3. The handheld transmitter does not transmit on 433 MHz!
    You can see this by the fact that the 'Press Button on your RC transmitter' does not do anything at all, even if the handheld transmitter is pressed. Perhaps there is a description of your radio, in which the transmission frequency is written
  4. The wireless protocol is not known to the software!
    Then you can try detect the protocol yourself via the expert settings - see Expert settings.

What can you do if the teach-in of a device worked, but the receiver does not respond?

  1. Maybe the receiver is too far away!
    Shorten the distance between receiver and board / Raspberry Pi. 
  2. Maybe the automatically detected pulse length is not correct!
    Try to change the pulse length slightly (approx. +/- 10%).
  3. Possibly the recognized protocol is not correct!
    If the sender sends a protocol that is very similar to a known protocol, it is possible that a sequence of digits is displayed but the protocol is still not correct.
    When recognizing / sniffing a radio signal, tolerances must be used, this can lead to a protocol seemingly being recognized.
    In this case you can try to control the protocol via the expert settings and create your own protocol - see Expert settings.
 





Standalone Actions

Standalone actions are independent sequences that can be started without an external control software (e.g. liveSHOW software).

To start such an action / process, it can be assigned to an Input (Input - see above).



With a click on  a new independent action / sequence is created.
Click on  to delete the action.

To assign what is triggered by the action, click on .
A new window will open:



A click on  adds a new item (a new table row) to the action.
Several items may be added to an action, which are executed simultaneously when the action is started.
The behavior of an item can be specified in the table row by double-clicking on a cell in the table.

Times can be entered in milliseconds or in the format hh:mm:ss:milliseconds. The time is always displayed in hours:minutes:seconds:milliseconds format.

Note: the changes to the parameters of an element are applied immediately. To save the changes permanently you have to click on 
after closing this window.

Action Here you can define which output (motor, LED, RC ...) is controlled by the item.
If you double click on an 'Action' cell, you can select one from a list of available outputs.
'---' means that no output is addressed.
Note: In the current version of the software the list of outputs is not sorted.
Start Here you can specify a start time/delay when the item starts,
You can simply enter milliseconds or a text in the format hh:mm:ss:milliiseconds.
max Value % If the output accepts values (motor, LED), you can specify the maximum value in percent here.
For outputs like RC or relay the value is not considered.
Fade In If the output accepts values (motor, LED) you can set the time until the maximum value is reached.
Outputs such as RC or relays switch immediately after the start time (there is no fading).
Faded in specifies the time after threading (Start + Fade In)
Length Here you can enter the time how long the item runs with maximum value.
Fade Out If the output accepts values (motor, LED) you can set the time until the maximum value reaches 0 (zero position).
Outputs like RC or relays switch off after the fade out time (there is no fade out).
Total Specifies the total duration of the item. (Fade In + Length + Fade Out)
End Specifies when the item is completely played. (Start + Fade In + Length + Fade Out)
A double click on the garbage can deletes the line / the item.

With the items and their parameters, complex processes for an action can be realized.

There are two ways to play such a sequence:
  1. play/stop
    Here the elements are simply played until the last element is finished.
    If 'play/stop' is pressed again before the end, the sequence is aborted and all involved outputs are set to 0 (zero position).
  2. fade in/out
    Here the sequence stops at the longest fade-in time. This is the case if the last item was faded in (Start + Fade In).
    Pressing the 'fade in/out' button again after the sequence has stopped will restart it. The sequence is finished when the last element is finished (longest end time).
    If 'fade in/out' is pressed again before the sequence is stopped (longest faded in time), the sequence is aborted and all involved outputs are set to 0 (zero position).
Examples for 2.:
or or

 The process stops with 'fade in/out' at the red line, the longest faded in time (Start + Fade In).

.
To test the settings directly, there are the buttons   und .
If you click on one of the Test buttons the sequence starts.

Clicking the Test button again (or activating an  input) causes the following behavior:
Note on the RC outputs:
RC Permanent: as long as an element is played the radio command is sent.
RC Once: if an element is started, the radio command is sent once.
RC On/Off: when an element is started the On radio command is sent, when an element is ended the OFF radio command is sent.

Note on Relais
Relais can not be faded in or out.
As soon as an element is played, the relay is closed.
When an element is ended, the relay is opened.

The field  displays the playback status. The color changes depending on the status:
Black = nothing is played
Gray = Playback has been started, but no element has been started yet (play time < start time)
Light green = at least one element is played
Special feature of fade in/out
Red = The sequence has stopped after the longest faded-in time (red line)
Dark green = The sequence was started again (fade out)



Starting an action via a keystroke or mouse click
Below each action there is a line where a key or a mouse click can be assigned for play/stop and/or fade in/out.



Assign a key or a mouse click:
A click on deletes the assigned keys.

Calling an action:
Above the actions there is a remote field


When you move the mouse over the remote field, it gets a green background.
Now you can press a key / mouse button to trigger the corresponding action.

Notes for triggering the actions via the keyboard or mouse:
You must make sure that the mouse pointer is over the remote field.
When starting the software (after booting the RaspberryPi) the mouse pointer is automatically moved to the remote field.





The control on the example of the liveSHOWsoftware

If you click on 'Media' in the menu of the liveSHOW software and then on 'Triggers',
a window opens in which all trigger types of all connected SPIT clients are listed.
In the case of the Raspberry Pi, the components and commands described above are listed - if the Raspberry Pi and the computer running the liveSHOW software have a network connection.



If you click on one of the listed trigger types and drag it into the Media Tracks on the Timeline while holding down the left mouse button, a trigger object is created there.



Whenever the play cursor is in the object, the trigger is triggered. If the play cursor moves out of the object, the trigger is terminated.



With motor-trigger objects, the maximum deflection of the servo motor can be set via the middle handle. A setting above the center line (>1.0) has no further effect. A setting below the center line (<1.0) reduces the maximum deflection of the motor. An fadein/fadeoff  moves the servo motor accordingly.

With relay-trigger objects, the relay is closed when the cursor is in the object and opened when the cursor moves out of the object.

For LED-trigger objects, the maximum brightness of the LED can be set using the middle handle.  An fadein/fadeoff dims the LED accordingly.

With RC-trigger objects the radio command is sent as set in the SPIT_GPIO software.
Inputs are not listed because the Raspberry Pi sends remote control trigger objects to the liveSHOW software when an input is changed - the way works the other way around here.

You can also drag a trigger type into a media jingle and use the trigger later by playing the jingle.



A trigger object in the liveSHOW software is displayed with a red frame if the connection to the client (SPIT_GPIO software) is terminated or the trigger no longer exists at the client (SPIT_GPIO software).


Note:
If you drag the same trigger (e.g. R1_LED_1 in the image above) into the timeline and into the jingle window and then play both trigger objects simultaneously, the output (here e.g. LED_1) will flicker.
You must avoid accessing the same output (trigger) simultaneously from the timeline and from a jingle.
If you play different outputs (triggers) in the timeline (e.g. LED_1) and in a jingle (e.g. Motor_1), this is not a problem.