Explorer HAT Pro I/O Provider Guide¶

Overview¶

The Explorer HAT Pro provider gives PiPLC access to all hardware I/O on the Pimoroni Explorer HAT Pro add-on board for Raspberry Pi. Unlike the generic GPIO provider, this provider has a fixed hardware mapping with no pin configuration required — select the provider type and start programming.

The board provides digital inputs, digital outputs (via ULN2003A Darlington driver), LEDs, capacitive touch pads (CAP1208 over I2C), analog inputs (ADS1015 ADC over I2C), and two motor outputs (DRV8833 dual H-bridge with software PWM).

Requirements¶

• Raspberry Pi with Explorer HAT Pro attached
• PiPLC ARM64 .deb package (Debian Trixie)
• I2C enabled on the Raspberry Pi (sudo raspi-config > Interface Options > I2C)

Hardware Setup¶

1. Attach the Explorer HAT Pro to the Raspberry Pi GPIO header.
2. Enable I2C if not already enabled:

   sudo raspi-config nonint do_i2c 0
   

3. Verify the board is detected:

   i2cdetect -y 1
   

   You should see devices at addresses 0x28 (CAP1208 touch controller) and 0x48 (ADS1015 ADC).

PLC Memory Map¶

The Explorer HAT Pro maps to fixed PLC addresses. No .ioconfig pin configuration is needed.

Digital Inputs (I: region)¶

Digital Outputs (O: region)¶

Analog Inputs (N: region, read)¶

Analog Outputs (N: region, write)¶

Selecting the Provider¶

On the Raspberry Pi (local)¶

1. Open the I/O Config panel (View > I/O Config).
2. Select Explorer HAT Pro from the Provider Type combo box.
3. Click Apply (engine must be stopped).

No further pin configuration is needed. The digital pin and analog channel tables are disabled since all mappings are fixed by the hardware.

From a Remote Windows/Linux Editor¶

1. Connect to the Raspberry Pi engine (Connection > Connect to Remote Engine).
2. Open the I/O Config panel.
3. Select Explorer HAT Pro and click Apply.

The provider type is available on all platforms for configuring remote engines. The hardware driver runs on the Raspberry Pi side.

Via Command Line¶

Create an .ioconfig file:

{
    "version": 1,
    "provider": "explorer_hat_pro"
}

Load it when starting the engine:

piplc-engine --ioconfig /path/to/explorer-hat.ioconfig

Motor Control¶

Motors are controlled through a combination of direction bits and speed words.

Direction¶

Set motor direction using the output bits:

Motor 2 uses O:0/10 (forward) and O:0/11 (backward) identically.

Speed¶

Set motor speed by writing a value 0–100 to the speed word:

• N:4 — Motor 1 speed (0% = stopped, 100% = full speed)
• N:5 — Motor 2 speed

The software PWM runs at approximately 1 kHz. The direction bits gate which GPIO receives the PWM signal.

Example: Run Motor 1 Forward at 75%¶

Rung 0:  |--[ XIC I:0/0 ]--[ OTE O:0/8 ]--|   (Input 1 enables forward)
Rung 1:  |--[ XIC I:0/0 ]--[ MOV 75 N:4 ]--|   (Set speed to 75%)
Rung 2:  |--[ XIO I:0/0 ]--[ MOV 0  N:4 ]--|   (Clear speed when stopped)

When Input 1 is pressed, Motor 1 runs forward at 75% duty cycle. When released, the speed is set to 0 and the direction bit clears.

Analog Input (ADC)¶

The four ADC channels read voltage on the Explorer HAT Pro's analog input pads (labeled 1–4 on the board). The ADS1015 returns a 12-bit value. In PiPLC, the raw 12-bit value (0–2047) is stored directly in N:0 through N:3.

Example: Threshold Detection¶

Rung 0:  |--[ GRT N:0 1000 ]--[ OTE O:0/4 ]--|   (Blue LED on if ADC1 > 1000)

Voltage Conversion¶

To convert the raw ADC value to millivolts (0–3300 mV range):

Rung 0:  |--[ MUL N:0 3300 N:10 ]--|   (raw * 3300)
Rung 1:  |--[ DIV N:10 2047 N:11 ]--|   (÷ 2047 = millivolts)

Touch Pads and Crocodile Clips¶

The CAP1208 provides 8 capacitive touch channels over I2C. The board labels them 1–8: touch pads 1–4 (I:0/4 – I:0/7, CAP1208 channels 5–8) and crocodile clips 5–8 (I:0/8 – I:0/11, CAP1208 channels 1–4). The crocodile clips can sense touch on conductive objects connected to the clips.

All 8 channels behave like digital inputs — ON when touched, OFF when released. The CAP1208 handles debouncing internally.

Example: Touch-Activated LED¶

Rung 0:  |--[ XIC I:0/4 ]--[ OTE O:0/4 ]--|   (Touch pad 1 lights blue LED)
Rung 1:  |--[ XIC I:0/5 ]--[ OTE O:0/5 ]--|   (Touch pad 2 lights yellow LED)

Safe State Behavior¶

When the PLC engine stops or faults, applySafeState() is called automatically:

• All digital outputs (1–4) are driven LOW
• All LEDs are turned OFF
• Motor speeds are set to 0%
• Motor direction enables are cleared
• The PWM thread stops modulating

This ensures motors and outputs are de-energized on any fault condition.

Troubleshooting¶

"I2C device not found" on initialize¶

• Verify I2C is enabled: sudo raspi-config nonint get_i2c (should return 0)
• Check the board is detected: i2cdetect -y 1
• Ensure /dev/i2c-1 exists and the user has permission (add user to i2c group: sudo usermod -aG i2c $USER)

Touch pads not responding¶

• The CAP1208 requires direct skin contact with the conductive pads on the board.
• If the product ID check fails during initialization, the provider will log an error. Check journalctl -u piplc-engine for details.

Motor runs but speed doesn't change¶

• Verify the speed word (N:4 or N:5) is being written each scan. A MOV instruction must continuously set the value.
• The direction bit (O:0/8–11) must also be ON for the corresponding motor direction — the PWM only modulates GPIOs that have their enable bit set.

ADC readings are noisy or zero¶

• Check wiring to the analog input pads on the board.
• The ADS1015 uses single-shot conversion mode. Each channel is read sequentially during the scan cycle, which adds a small amount of scan time.

See Also¶

• Memory Regions — PLC address format reference
• Instruction Reference — All 30 instruction types
• GPIO Architecture — I/O provider architecture
• Getting Started — Installation and setup