RElay board

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

DISCLAIMER

We do not take any responsibility for possible errors in the guide or errors that you might do wiring it up. Incorrect wiring can result in damaged sensor or damaged Raspberry Pi.

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:

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.

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.

Connecting to the Raspberry Pi

In my example then I have it connected as follows:

Raspberry Pi pin layout

If you need more information about the GPIO headers on Raspberry Pi or other boards then click bellow.

Raspberry Pi Pin guideOrange Pi One Pin guideOrange Pi Pin guide for most H3 modelsOrange Pi Zero 3 Pin  guideOrange Pi 5 Plus Pin guideRock 64 Pin guide

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.

If you are not familiar with working with a breadboard or on how to place a cobbler on the breadboard then click here bellow

Breadboard

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

Getting the code

You can find this example code at Example code for GPIO guides.