Actuators — Relays, Smart Plugs, Servos, Dosing Pumps, and Sequent HATs

Actuators are the parts in your LoopString system that do things: they switch power on and off, open and close valves, move mechanical components, and pump fluids. This page covers every actuator part available in the Configurator, how to wire and configure each one, and — critically — which controller type you must pair with each actuator.

New: For brewing and industrial actuators (heaters, glycol chillers, mixers, linear actuators, and level sensors), see Brewing & Industrial Actuators. For time-based actuator control (delays, intervals, cron schedules), see Timers & Scheduling. For proportional relay control via PID, see PWM Duty Cycle Adapter.

Critical Concept: Binary vs. Analog Actuators

Before adding any actuator to your project, you need to understand whether it is a binary actuator or an analog actuator. Getting this wrong is the most common source of support issues on the platform.

Binary actuators accept a simple on/off command. They are either fully on or fully off — there is no middle ground. Relay modules, Kasa smart plugs, solenoid valves, and relay-driven dosing pumps are all binary actuators.

Analog actuators accept a continuous numeric value, usually a percentage from 0 to 100 or an angle from 0 to 180. They can be set to any point in their range. PWM dosing pumps, SG90 servo motors, PWM fan controllers, and Sequent analog output channels are analog actuators.

Controller Compatibility — The Most Important Rule

Binary actuators must be paired with a Hysteresis controller. A hysteresis controller outputs a clean on/off signal based on whether a sensor reading has crossed a threshold. This is exactly what a relay or smart plug needs.

Analog actuators must be paired with a PID controller (or a manual setpoint). A PID controller outputs a continuous value — for example, 63% — representing how hard to work to reach a target. A relay cannot interpret 63%. It only knows on or off. If you wire a PID output directly to a relay or a Kasa smart plug, the relay will click on and off rapidly, which damages both the relay and whatever load is connected to it.

Exception: You can use a PID controller with a binary actuator if you add a PWM Duty Cycle Adapter between them. The adapter converts the PID's continuous output into timed on/off pulses, giving proportional-like control.

Here is a quick reference:

Binary actuators — use Hysteresis controller:

• GPIO relay module (single channel)
• Kasa HS103 smart plug
• 12V solenoid valve (relay-driven)
• 12V dosing pump (relay-driven, on/off pulse)
• Sequent 8-Relay HAT (sm-8relay-hat)
• Sequent 16-Relay HAT (sm-16relay-hat)
• Sequent Home Automation HAT relays (sm-ioplus-hat)
• Sequent Building Automation HAT TRIAC outputs (sm-bas-hat)
• Pi GPIO Fan (On/Off)
• Heater Actuator (relay-driven)
• Glycol Chiller (relay-driven pump)
• Mixer/Agitator (relay-driven motor)

Analog actuators — use PID controller or setpoint:

• SG90 servo motor (angle 0–180°)
• Variable-speed dosing pump, PWM (duty cycle 0–100%)
• Sequent Building Automation HAT 0–10V analog outputs
• Sequent Smart Fan HAT (speed 0–100%)
• Pi GPIO Fan (PWM)
• Linear Actuator (PWM mode)

Overview of All Actuator Parts

GPIO Relay Modules (Single-Channel, Used Inline)

GPIO relay modules are small circuit boards that let a Raspberry Pi GPIO pin switch a higher-voltage load. The relay acts as an electrically controlled switch: when the Pi sends a signal to the relay's IN pin, the relay's contacts open or close, switching whatever load is wired through them.

The most common use of a relay in LoopString is not as a standalone part but embedded inside other actuator parts. The Dosing Pump (relay), Solenoid Valve, and the Pi GPIO Fan (On/Off) all use a GPIO-driven relay internally. You wire the relay module to a GPIO pin, and the relay coil is powered from the Pi's 5V rail.

Relay modules come as active-low or active-high. Most inexpensive relay boards sold online are active-low: the relay coil is energized (and the relay closes) when the GPIO pin is pulled LOW. When the GPIO pin is HIGH, the relay is open. This behavior is the opposite of what you might expect, and getting it wrong will cause your load to be on by default. Always check the "Relay Active State" setting in the Configurator to match your specific relay board.

Key specs:

• GPIO signal required: 1 pin per channel
• Relay coil powered from Pi 5V rail
• Load voltage: depends on relay rating (commonly 10A at 120VAC for standard boards)
• Load is wired through the relay's COM and NO (normally-open) or NC (normally-closed) terminals

Controller compatibility: Hysteresis only.

TP-Link Kasa HS103 Smart Plug (kasa-hs103)

The Kasa HS103 is a WiFi-connected smart outlet. You plug it into a standard wall outlet, then plug your load (heater, fan, humidifier, grow light) into the Kasa plug. Node-RED controls the plug directly over your local network using the Kasa LAN API — no cloud account is required after initial WiFi setup.

This is the easiest actuator to wire: there is no soldering or GPIO wiring. You just need the plug on the same WiFi network as your Pi.

Configuration options:

• Device Alias — the friendly name you gave the plug in the Kasa app (e.g., "Warm Humidifier")
• Local IP Address — the plug's IP address on your local network (must be a valid IPv4 address, e.g., 192.168.1.45)

Setup steps:

1. Plug the HS103 into a wall outlet.
2. Use the Kasa mobile app to connect it to your WiFi network. The plug must be on the same local network as the Raspberry Pi.
3. In your router's admin panel, assign a static (reserved) IP address to the plug using its MAC address. This prevents the IP from changing after a power cycle or router reboot. If the IP changes and you have not updated the Configurator, Node-RED will lose control of the plug.
4. Enter the static IP address in the Configurator.

Controller compatibility: Hysteresis only. Never connect a PID output directly to a Kasa smart plug. The Kasa plug cannot modulate power smoothly — it is either fully on or fully off. A PID output of 63% means nothing to the plug. If you wire it this way, the plug will receive rapid on/off commands as the PID hunts, causing rapid cycling that stresses both the plug and the connected device. Use a hysteresis controller instead, which will command the plug on or off cleanly based on a temperature or humidity threshold.

Known issue: The Kasa LAN API requires the node-red-contrib-tplink Node-RED package. This package is installed automatically when you deploy from the Configurator, but it requires the Pi and the plug to be on the same subnet. Kasa plugs on a guest WiFi VLAN cannot be controlled.

SG90 Micro Servo Motor (sg90-servo-pwm)

The SG90 is a small positional servo motor that rotates to a specific angle between 0° and 180° based on a PWM signal. Unlike a regular motor that spins continuously, a servo holds position. This makes it useful for physical control tasks like opening and closing vent dampers, adjusting valve positions, and moving camera mounts.

The SG90 requires a hardware PWM GPIO pin. Only GPIO 12 (physical Pin 32) and GPIO 18 (physical Pin 12) support hardware PWM on the Raspberry Pi. GPIO 12 is recommended.

Configuration options:

• PWM GPIO Pin (BCM) — choose GPIO 12 or GPIO 18. GPIO 12 is the default and recommended for most uses.

Wiring:

1. Power off the Pi before wiring.
2. Connect the servo orange or yellow signal wire to GPIO 12 (Pin 32).
3. Connect the servo red wire to Pi 5V (Pin 2).
4. Connect the servo brown or black wire to Pi GND (Pin 6).

If you are running more than one servo, do not power them from the Pi 5V rail. Draw more than about 250mA from the rail and the Pi may become unstable. Use a dedicated 5V power supply for the servos, sharing a common GND with the Pi.

How angle control works: The flow generator converts the incoming angle value (0–180°) to a PWM duty cycle between 5% and 10% at 50Hz. A duty cycle of 5% corresponds to 0°, and 10% corresponds to 180°.

Controller compatibility: Analog. Connect the output of a PID controller or a manual setpoint to the SG90 servo input. The value should represent the target angle in degrees.

12V Peristaltic Dosing Pump — Relay-Driven (dosing-pump-relay)

This is a 12V peristaltic pump controlled by a single GPIO relay. Peristaltic pumps move liquid by squeezing flexible tubing — no liquid contacts the pump mechanism, which makes them ideal for dosing nutrients, pH adjustment chemicals, and other liquids.

The relay version is binary: the pump is either running or stopped. You configure a pulse duration — how many milliseconds the pump runs per dose event. The flow rate depends on your specific pump's tubing and speed, so calibrate the pulse duration by measuring how much liquid is dispensed in a known time.

Configuration options:

• Relay GPIO Pin (BCM) — BCM GPIO pin connected to the relay IN signal. Default is GPIO 17 (Pin 11).
• Relay Active State — Active LOW for most relay boards; Active HIGH for some. Default is Active LOW.
• Default Pulse Duration — How long the pump runs per dose event, in milliseconds. Range 100ms–30,000ms. Default 2,000ms.

Wiring:

1. Power off the Pi. Never power the 12V pump from the Pi.
2. Connect relay IN to GPIO 17 (Pin 11) or your chosen GPIO pin.
3. Connect relay VCC to Pi 5V (Pin 2) and relay GND to Pi GND (Pin 6).
4. Wire the 12V pump motor through the relay COM and NO terminals, using a separate 12V power supply.

Controller compatibility: Hysteresis or manual toggle. The pump is binary — on or off. Use a hysteresis controller to automatically dose when a sensor reading (e.g., nutrient concentration, pH) crosses a threshold, or use manual control from the dashboard.

Variable-Speed Peristaltic Dosing Pump — PWM (dosing-pump-pwm)

The PWM dosing pump is a variable-speed version of the dosing pump. Instead of a relay, it uses a motor driver board (such as L298N or BTS7960) connected to a hardware PWM GPIO pin. A duty cycle percentage from 0% to 100% sets the pump speed and therefore the flow rate.

This part is used when you need proportional chemical dosing — for example, when a PID controller is regulating pH and needs to dose acid or base at varying rates to avoid overshooting.

Configuration options:

• PWM GPIO Pin (BCM) — GPIO pin for the PWM signal. GPIO 18 is recommended (supports hardware PWM on all Pi models). Default is GPIO 18.
• PWM Frequency (Hz) — Switching frequency for the motor driver. Most L298N and BTS7960 drivers work at 100–500Hz. Default is 200Hz.
• Max Flow Rate (mL/min) — The pump's full-speed flow rate at 100% duty cycle. Used to display estimated dosing volume on the dashboard. Default is 100 mL/min.

Wiring:

1. Power off the Pi.
2. Connect the motor driver IN pin to GPIO 18 (Pin 12) or your chosen GPIO pin.
3. Connect the external 12V supply to the motor driver VM terminal.
4. Connect Pi GND (Pin 6) and the 12V supply GND to a common ground rail.

Controller compatibility: Analog. Connect a PID output or a numeric setpoint to the pump input. The value represents duty cycle from 0 to 100%.

12V Solenoid Valve — Relay-Driven (solenoid-valve-12v)

Solenoid valves are electrically controlled valves that open or close when power is applied. The 12V solenoid valve part uses a GPIO-driven relay to switch the 12V coil. Most solenoid valves sold for irrigation and aquaponics are normally closed (NC): water cannot flow when unpowered, and the valve opens when the relay energizes the coil.

Configuration options:

• Relay GPIO Pin (BCM) — BCM GPIO pin connected to the relay. Default is GPIO 27.
• Relay Active State — Active LOW for most relay boards; Active HIGH for others. Default is Active LOW.

Wiring:

1. Power off the Pi.
2. Connect relay IN to your chosen GPIO pin.
3. Connect relay VCC to Pi 5V (Pin 2) and GND to Pi GND (Pin 6).
4. Wire the solenoid valve through the relay COM and NO terminals using a separate 12V supply.
5. Add a flyback diode (1N4007 or equivalent) across the solenoid coil terminals. Solenoids are inductive loads and will spike voltage when switched off, which can damage the relay or Pi GPIO.

Controller compatibility: Hysteresis or manual toggle. Solenoid valves are binary — open or closed.

Sequent Microsystems HATs

Sequent Microsystems produces a line of stackable HATs (Hardware Attached on Top) for Raspberry Pi. These HATs plug directly onto the Pi's 40-pin GPIO header and are controlled via the I2C bus. Up to 8 HATs of the same type can be stacked on a single Pi, with each HAT assigned a unique stack level via solder jumpers on the PCB.

Sequent HATs are ideal when you need more actuator channels than a Pi can provide via GPIO, or when you need professional-grade output isolation (triacs, 4-20mA loops).

Stack Level Configuration

Every Sequent HAT has a Stack Level setting (0–7). This maps to the I2C address the HAT will respond to. Stack level 0 is the default and is what you need unless you are adding a second HAT of the same type. When stacking multiple HATs, set each to a different stack level and make sure the physical jumpers on the PCB match the level you set in the Configurator.

Important: The 8-Relay HAT and the 16-Relay HAT share the same I2C address range (0x20–0x27). You cannot mix these two HAT types on a single Pi.

Sequent 8-Relay HAT (sm-8relay-hat)

An 8-channel relay HAT. Each relay is rated 4A at 120VAC or 30VDC. Each channel has COM, NO (normally open), and NC (normally closed) terminals. Wire your load between COM and NO for normally-open operation (load is off by default). Up to 8 of these HATs can be stacked on one Pi, giving you up to 64 individually controlled relay channels.

Configuration options:

• Stack Level — Hardware stack level (0–7) matching the solder jumpers on the PCB.
• Relay Channels — Select which channels (1–8) you want to expose as wirable inputs in the flow editor. You do not need to use all 8.
• State Poll Interval — How often Node-RED reads back relay states from RTDB to confirm commands were received. Default is 5,000ms.

Controller compatibility: Hysteresis only. Each selected channel exposes a binary input in the flow editor.

Sequent 16-Relay HAT (sm-16relay-hat)

A 16-channel relay HAT (Sequent SM-I-013). Each relay has a normally-open contact rated 2A at 24VAC/DC. Up to 8 HATs can be stacked for 128 relays total. Includes RS485/MODBUS and a hardware watchdog.

Note: the 16-Relay HAT shares the I2C address range 0x20–0x27 with the 8-Relay HAT. Do not mix both HAT types on the same Pi.

Configuration options:

• Stack Level — Hardware stack level (0–7).
• Relay Channels — Select which channels (1–16) to expose as wirable inputs.
• State Poll Interval — How often Node-RED reads relay states from RTDB. Default is 5,000ms.

Controller compatibility: Hysteresis only.

Sequent Home Automation HAT — IO Plus (sm-ioplus-hat)

A mixed I/O HAT with 8 relays (6A at 24VAC/DC, with channels 6 and 7 limited to 3A), 8 analog inputs (0–3.3V, 12-bit), 4 DAC outputs (0–10V), and 4 open-drain PWM outputs. Up to 8 HATs can be stacked.

In the current version of LoopString, the relay outputs and analog inputs are supported. The 4 DAC outputs and 4 PWM outputs are available in a future update.

Configuration options:

• Stack Level — Hardware stack level (0–7). I2C addresses range from 0x28 (level 0) to 0x2F (level 7).
• Analog Input Channels — Select which analog input channels (AI1–AI8) to expose as sensor outputs. Each reads 0–3.3V as a 12-bit value.
• Analog Sample Interval — How often to read the analog inputs. Default is 30,000ms.

Controller compatibility: Relay outputs are binary (Hysteresis only). Analog inputs are sensor readings, not actuator outputs.

Sequent Building Automation HAT (sm-bas-hat)

The most versatile Sequent HAT. It includes 8 universal inputs (software-selectable between 0–10V analog, 1K thermistor, 10K thermistor, and dry contact/counter modes), 4 TRIAC outputs (24VAC, 1A each), and 4 analog 0–10V DAC outputs. Also includes a 1-Wire bus (for up to 16 DS18B20 temperature sensors), RS485/MODBUS, a real-time clock, and a hardware watchdog.

The I2C address range is 0x48–0x4F, which does not conflict with the relay HATs at 0x20–0x2F or the IO Plus HAT. You can run a Building Automation HAT alongside relay HATs on the same Pi.

Configuration options:

• Stack Level — Hardware stack level (0–7).
• TRIAC Output Channels — Select which TRIAC channels (1–4) to expose as wirable binary inputs. Each TRIAC switches 24VAC loads.
• Universal Input Mode — Select the mode for all 8 universal inputs: 0–10V analog, 1K thermistor, 10K thermistor, or dry contact. All 8 inputs share the same mode. Match the PCB jumper setting to this selection.
• Universal Input Channels — Select which input channels (1–8) to expose as sensor outputs.
• Analog Output Channels — Select which 0–10V DAC output channels (1–4) to expose as wirable analog inputs.

Controller compatibility: TRIAC outputs are binary (Hysteresis only). Analog 0–10V outputs are analog (connect PID output or setpoint). Universal inputs are sensor readings.

Sequent Smart Fan HAT (sm-sfan-hat)

A dedicated fan controller HAT that drives a 40×40×10mm fan via a built-in step-up converter. The HAT generates 12V from the Pi's 5V rail — no external power supply required. Fan speed is controlled from 0–100%. Maximum 2 Smart Fan HATs per Pi.

Configuration options:

• Stack Level — 0 or 1 only (I2C addresses 0x03 and 0x04).
• State Poll Interval — How often Node-RED reads the fan speed setpoint from RTDB. Default is 5,000ms.

Controller compatibility: Analog. Connect a PID output or numeric setpoint representing 0–100% speed.

How to Add an Actuator in the Configurator

1. Open your Configurator project (or create a new one — see Creating a Project).
2. In the Parts panel on the left, switch to the Actuators filter or search for the actuator you want.
3. Drag the actuator part into a room in the canvas.
4. Click the part to open its settings panel. Fill in all required fields (GPIO pin, IP address, stack level, etc.).
5. In the flow editor, find the actuator node. It will have one or more input ports on its left side.
6. Connect the output of a controller (hysteresis or PID, depending on the actuator type) to the actuator's input port.
7. Validate the project using the Validate button in the toolbar. Fix any warnings before deploying.
8. Deploy to your Pi using the Deploy button.

Real-World Use Cases

Automated Mushroom Fruiting Chamber

A common grow room setup uses temperature and humidity control. You would add:

• A DHT22 temperature and humidity sensor
• A Kasa HS103 smart plug to control a space heater (binary, hysteresis)
• A second Kasa HS103 for a cool mist humidifier (binary, hysteresis)
• A hysteresis controller for temperature, wired to the heater plug
• A hysteresis controller for humidity, wired to the humidifier plug

The hysteresis controllers turn the heater on when temperature drops below the lower threshold and off when it rises above the upper threshold, preventing rapid cycling. The Kasa plugs handle the mains switching without any relay wiring.

Hydroponic Nutrient Dosing System

For automated pH and EC management you would add:

• An Atlas Scientific EZO pH sensor
• A 12V peristaltic dosing pump (relay-driven) for pH down solution
• A second dosing pump for pH up solution
• A hysteresis controller for pH, configured with separate high and low thresholds for each pump

The hysteresis controller pulses one pump on briefly when pH is too high, and the other when pH is too low. You tune the pulse duration in the dosing pump settings to match your pump's flow rate so each activation adds the correct volume.

Troubleshooting

Kasa plug stops responding after a network change

The most common cause is that the plug received a new IP address from your router (DHCP reassigned it). The fix is to assign a static IP reservation for the plug in your router's admin panel using the plug's MAC address, then update the IP address in the Configurator and redeploy. Going forward, the plug will always have the same IP.

If you cannot assign a static IP, you can find the current IP by opening the Kasa app and viewing the plug's device details.

Relay clicks rapidly on and off

This almost always means a PID controller output is connected to a binary actuator (relay or Kasa plug). A PID output is a continuous value; the relay interprets rapid commands from the control loop as rapid switching. Change the controller to a hysteresis type, or add a PWM Duty Cycle Adapter between the PID and the relay for proportional control, or rewire the flow so the PID output drives an analog actuator instead.

If the rapid clicking is on a Sequent relay HAT, also check that the State Poll Interval is not set too short — a very short poll interval can cause command flooding.

Servo motor jitters or holds wrong angle

This usually means the wrong PWM pin is selected. The SG90 servo requires a hardware PWM pin (GPIO 12 or GPIO 18). If you connect it to a non-PWM GPIO pin, the signal will be software-generated and imprecise, causing jitter. Switch to GPIO 12 (Pin 32) in the part settings.

If powering multiple servos from the Pi 5V rail, jitter can also be caused by voltage sag. Move to a dedicated 5V supply for the servos.

Sequent HAT not responding / relay states not updating

Check these items in order:

1. Confirm the stack level in the Configurator matches the physical solder jumpers on the HAT PCB.
2. Verify I2C is enabled on the Pi: run sudo raspi-config , go to Interface Options, and enable I2C.
3. Run i2cdetect -y 1 on the Pi to scan for connected I2C devices. The HAT's I2C address should appear.
4. If mixing HAT types, confirm you are not using the 8-Relay HAT and 16-Relay HAT together (they share the same I2C address range and will conflict).
5. Redeploy the flow after changing any HAT settings.

Known Issues and Limitations

Kasa HS103 and PID mismatch is silent: The Configurator does not currently prevent you from wiring a PID output to a Kasa plug. It is the user's responsibility to use a hysteresis controller for binary actuators. A future update will add validation warnings for this misconfiguration.

Kasa LAN API requires same subnet: If your Pi is on a wired Ethernet network and your Kasa plug is on a WiFi VLAN or guest network, Node-RED cannot reach the plug. Both must be on the same layer-2 network segment.

Home Automation HAT (IO Plus) DAC outputs not yet supported: The 4 analog 0–10V DAC output channels and 4 open-drain PWM outputs on the IO Plus HAT are not yet wirable in the flow editor. Only the relay outputs and analog inputs are functional in the current release.

SG90 servo maximum torque is very low: The SG90 is a micro servo intended for lightweight loads. It is not suitable for controlling dampers or valves with significant spring pressure. For higher-torque applications, use the MG996R or equivalent and wire it the same way, but power it from an external 5V supply.

Multiple Kasa plugs require unique IP addresses: Each Kasa HS103 in your project must have a unique static IP. If two plugs share the same IP (which cannot happen on a real network but can happen if you misconfigure the Configurator), only one will respond.

Related Documentation

• Brewing & Industrial Actuators — heaters, chillers, mixers, linear actuators, level sensors
• PWM Duty Cycle Adapter — proportional relay control via PID
• Timers & Scheduling — time-based actuator control
• Configurator Overview — understanding the Configurator interface
• Adding Rooms and Parts — how to add parts to a project
• Wiring Flows — how to connect parts together in the flow editor
• Deploying to Pi — how to send your configuration to the Raspberry Pi