Sensor Wiring
All KY-series modules follow the same basic wiring pattern. Connect VCC to 3V3, GND to ground, and DO (digital output) to a GPIO pin. The dashboard shows the wiring table for each sensor when you select it.
All GPIO pin numbers below use BCM numbering (the GPIO number), not the physical board pin number. The board pin is shown in brackets for reference.
Interactive Pinout
VCC→3V3 Powerpin 17GND→Groundpin 14DO→GPIO 22pin 15Reed Switch (KY-025)
Magnetic reed switch - triggers when the magnet is removed (door opens). This is the default sensor and is already documented in the hardware setup.
pin 17pin 14pin 15The KY-025 has a fourth pin marked AO (analog output) - this is not used since the Raspberry Pi doesn't have analog inputs.
Mini Reed Switch (KY-021)
Compact reed switch - functionally identical to the KY-025 but in a smaller package. Only has 2 pins - no VCC needed because the software enables an internal pull-up resistor on the GPIO pin.
pin 14pin 38Hall Magnetic Sensor (KY-003)
Digital Hall-effect sensor - detects the presence of a magnetic field using a Hall-effect IC instead of a mechanical reed contact. No moving parts means longer lifespan. Works the same way as a reed switch: attach a magnet to the door, the sensor detects when it moves away.
pin 17pin 14pin 33Hall Linear Sensor (KY-024)
Linear Hall-effect sensor with an adjustable threshold potentiometer. Functionally similar to the KY-003 but lets you fine-tune the magnetic field strength needed to trigger. Useful when the magnet distance varies or you need more precise control.
pin 17pin 14pin 32Adjust the onboard potentiometer to set the magnetic field trigger threshold. Ignore the AO (analog) pin.
PIR Motion Sensor (HC-SR501)
Any standard HC-SR501 (or similar) passive infrared motion sensor. Detects heat and movement - ideal for room or hallway monitoring.
pin 2pin 6pin 11PIR modules need 5V power (not 3.3V). The output signal is still 3.3V-safe for the GPIO pin.
Most PIR modules have two potentiometers on the back: one for sensitivity and one for the output hold time. Set the hardware hold time short (1-2 seconds) and use the software hold timeout instead - this gives you more control from the dashboard.
Vibration / Shock Sensor (KY-002)
Spring-contact vibration sensor - produces brief digital pulses on impact. Good for detecting door slams, forced entry attempts, or window impacts. Because the output is pulsed (not sustained), the hold timeout is important - it keeps recording running through repeated vibrations.
pin 17pin 14pin 29For door/window monitoring, mount the sensor directly on the frame so it picks up vibrations from opening, closing, or impact.
Knock / Tap Sensor (KY-031)
Spring-contact knock sensor - similar to the KY-002 vibration sensor but tuned for deliberate taps and knocks rather than sustained vibration. Produces brief pulses.
pin 17pin 14pin 35Light Gate / Photo Interrupter (KY-010)
Small slotted optical sensor with an IR emitter and receiver on opposite sides of a ~5mm gap. Triggers when the infrared beam is blocked. The slot is very narrow, so this sensor requires some mechanical effort to mount - typically you position a pin, bolt, or similar object inside the slot so that removing it breaks the beam and triggers the alarm.
pin 17pin 14pin 31For a simple alarm, insert a pin or folded piece of card into the slot. When someone pulls it out, the beam is restored/broken and recording triggers.
IR Proximity Sensor (KY-032)
Infrared obstacle avoidance sensor - triggers when an object comes within range. The onboard potentiometer lets you set the detection distance from roughly 2 to 40 cm. The sensor outputs LOW when an object is detected, so enable Invert trigger in the dashboard.
pin 17pin 14pin 18Tilt Switch (KY-017)
Mercury tilt switch - triggers when the sensor is tilted beyond its threshold angle. Mount it on the camera itself for tamper detection - if someone moves or repositions the camera, recording starts.
pin 17pin 14pin 37The KY-017 contains a small amount of mercury. Handle with care and do not break the glass capsule.
Tilt Switch - Ball (KY-020)
Ball tilt switch - a mercury-free alternative to the KY-017. Uses a metal ball instead of mercury to detect orientation changes. Functionally identical but safer to handle.
pin 17pin 14pin 22Touch Sensor (KY-036)
Capacitive metal touch sensor - triggers when a person touches the metal contact pad. The sensor detects the electrical conductivity of skin.
pin 17pin 14pin 36You can extend the touch surface by soldering a wire from the sensor pad to a larger metal surface (e.g. a door handle or metal plate).
Sound Sensor - High Sensitivity (KY-037)
High-sensitivity microphone module - triggers on loud sounds like glass breaking, door slamming, or shouting. The larger microphone capsule picks up sounds from further away than the KY-038.
pin 17pin 14pin 16Adjust the onboard potentiometer to set the sound trigger threshold. Start with a high threshold (less sensitive) and decrease until it triggers reliably on the sounds you want to detect. Ignore the AO (analog) pin.
Sound Sensor - Standard (KY-038)
Standard microphone module - less sensitive than the KY-037 but better for close-range detection. Good for detecting knocking, tapping, or nearby noises without picking up ambient sound from across the room.
pin 17pin 14pin 24Adjust the onboard potentiometer to set the sound trigger threshold. Ignore the AO (analog) pin.
Push Button
Any momentary push button works. The software enables an internal pull-up resistor, so no external components are needed - just wire the button between a GPIO pin and GND.
pin 13pin 14Mock Sensor (Software Only)
No hardware needed - the mock sensor lets you test the full recording pipeline without any physical sensor connected.
- Go to Settings > Sensors
- Select Mock from the sensor type grid
- Click Save Configuration
- Toggle Auto-recording on
- The Mock Sensor Controls panel appears with Simulate Trigger and Simulate Release buttons
You can also trigger and release via the REST API.