RElay board

In this example we are going to wire up a relay board and let your Xojo code control it.

A relay board is normally used to control high voltage devices such as lights for example.  In my case I will be using them  to remote control electric heaters in a summer house in the winters when I am not there.

Make sure to know your relay board. It is important to know from its datasheet how much current the control pins will consume and how much current the 5V pins will consume. If you do not know how much current your relay will draw then you may need to measure it with Digital multimeter. 

A relay by it self would consume far to much current for Raspberry Pi pin to power it which is why the relay boards usually are set up with on board Optocouplers on them. 

If your relay board has separate GND for the 5V then you likely can drive the 5V on it from totally different power source if you wish.  My board only had one GND, so this was not possible on my board.

Be smart when doing projects with relays. If you have very large relay boards operating many relays at once then it will draw a lot of current from your Raspberry PI and the Raspberry PI does not allow you to draw unlimited amount of it. Max output for any single GPIO is 16 ma with total current from all GPIO pins at around 50 ma.

The relay I used draws around 4 ma from the GPIO pin when turning it to HIGH per relay. And it was draws around 14,5 ma from from 5V power
pin.  So powering all four of them would be taking around 16 ma from the GPIO’s total budget and around 58ma from the 5V pin. (How much your 5V pin can supply depends a bit on your power supply)

Pieces we use:

• Raspberry Pi 2, 3, 4 or 5. (or any of the boards known to work with the Gpiod Plugin)
• Cobbler and Cobbler cable.
• Breadbboard.
• 4 channel relay board.  (One or two channel are also fine, I just happened to have 4 channel)
• Gpiod Plugin for Xojo to use libpgiod in Xojo. The plugin you can get download here.  Or if you are interested in its source code then you can go here.

First thing is connecting the relay board:

I will only be wiring channel 1 and channel 3, leaving 2 and 4 unused in this example.

• (5V) Red is the 5V input, its marked as VCC on the board – I always use red for the power input.
• (GND) Blue is the ground. I always use blue for ground
• (GPIOX1) Yellow is connected to IN1 which means yellow will control relay 1 (We will choose this to be GPIO 4 further bellow)
• (GPIOX2) Green is connected to IN3 which means yellow will control relay 3 (We will choose this to be GPIO 17 further bellow)

To connect your high voltage device such as light bulb, then you use the high voltage connectors on the other side of the relay as shown on the picture above. Those you would connect as if you were connecting a switch.

• High voltage ground goes to the Bulb.
• High voltage input goes to the middle connector on the relay.
• High voltage output that goes from the relay to the bull will go either in the left or the right connector on the relay depending on if you want the bulb on or off when the relay is powered.

Connecting to the Raspberry Pi

In my example then I have it connected as follows:

• Red to pin 2 (5V)
• Blue to pin 6 (GND)
• Yellow to GPIO 4 which is pin 7.
• Green to GPIO 17 which is pin 11.

If you want your relays to have determined state before the Xojo application runs then you could put physical pull down resistors on the pins for example putting 1kΩ resistors between ground and the GPIO pins (one resistor for each of the two pins). That would pull the pin down into determined off state even if the Xojo Application has not been started.

The Xojo code for this one very simple:

I had a window, with two checkboxes on it, one says Relay 1 (GPIO 4) the other says Relay 2 (GPIO 17).

In the window I added the following property:

Private mLineRequest As Gpiod.LineRequest

And then Opening event to the Window:

Sub Opening() Handles Opening
  try
    using Gpiod
    
    var chip as Chip = Chip.Open("/dev/gpiochip0")
    
    // We call helper function to set up pin number 5 in output mode.
    mLineRequest = RequestOutputLine(chip, array(ctype(4, UInt32), ctype(17,Uint32)), "relay control")
    
  catch e as GpiodException
    MessageBox(e.Message)
  end try
End Sub

Notice that since all three pins have same settings then one line request is enough.

Public Function RequestOutputLine(chipHandle as Gpiod.Chip, lineOffsets() as UInt32, consumer as String) As Gpiod.LineRequest
  // Helper function to set up output pin.
  
  using Gpiod
  
  // Exceptions will be caught by the caller method
  
  var reqCfg as RequestConfig = nil
  
  var setting as new LineSetting()
  setting.Direction = Gpiod.Direction.OUTPUT
  setting.OutputValue = Gpiod.LineValue.INACTIVE
  setting.Bias = Gpiod.LineBias.PULL_DOWN
  
  var lineCfg as new LineConfig()
  lineCfg.AddLineSetting(lineOffsets,setting)
  
  if consumer <> "" then
    reqCfg = new RequestConfig()
    reqCfg.Consumer = consumer
  end if
  
  return chipHandle.RequestLines(reqCfg, lineCfg)
End Function

And finally ValueChanged events for the checkboxes:

Sub ValueChanged() Handles ValueChanged
  mLineRequest.Value(4) = if(me.Value, Gpiod.LineValue.ACTIVE, Gpiod.LineValue.INACTIVE)
End Sub

Sub ValueChanged() Handles ValueChanged
  mLineRequest.Value(17) = if(me.Value, Gpiod.LineValue.ACTIVE, Gpiod.LineValue.INACTIVE)
End Sub