Smart Lighting Using PiJuice Zero and Raspberry Pi Zero W

This project builds a battery-backed, locally controlled LED lamp from a Raspberry Pi Zero W, PiJuice Zero UPS HAT, high-power LED, MOSFET and web interface. It is reproducible, but it is an intermediate electronics and Linux build—not a plug-and-play smart bulb. The original 2019 design should also be modernized before use: create a unique Raspberry Pi account, avoid running the server as root, verify PiJuice software compatibility, and treat the lithium battery, high-current wiring and LED heat as serious safety concerns.

What the project does

The original project, published on Hackster.io on December 22, 2019, uses a Raspberry Pi Zero W to control a high-brightness LED through a PiJuice Zero UPS board. A browser on the same network provides on/off and dimming controls through a Python web server and WebSocket connection.

#	Preview	Product	Price
1		Freenove Raspberry Pi Pico 2 W Board Pre-Soldered Header, Dual Arm Cortex-M33 and Dual Hazard3...	$18.95	Buy on Amazon
2		SANOOV Raspberry Pi Zero 2W Kit	$119.99	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

The title of the original project says “Raspberry Pi Zero,” but the hardware is specifically the wireless Raspberry Pi Zero W. A plain Zero has no built-in Wi-Fi or Bluetooth. The system has five layers:

1. Controller: the Pi runs Linux, Python and the network service.
2. Power management: PiJuice charges and monitors the battery and provides backup power.
3. Controlled supply: PiJuice’s system-power output supplies the LED circuit.
4. Switching stage: an N-channel MOSFET modulates LED current using PWM from PiJuice I/O 2.
5. User interface: a browser sends commands over HTTP and WebSockets.

Browser
   │ Wi-Fi / WebSocket
   ▼
Raspberry Pi Zero W
   │ PiJuice API and PWM
   ▼
PiJuice Zero ─── Li-polymer battery
   │
   ▼
High-power LED circuit
   │
   └── MOSFET + current limiting or constant-current driver

What PiJuice Zero contributes

PiJuice Zero is a Raspberry Pi UPS and power-management board, not an LED controller. In this application it provides battery charging, power-source and battery-status reporting, backup operation, a controllable system-power output and configurable I/O. The original project describes the system output as providing up to 2.1 A to a peripheral and uses a PWM-capable I/O pin. Treat those figures as characteristics of the documented project and exact PiJuice revision, not universal ratings; verify the board’s current documentation before selecting the LED load.

#1 Best Overall

Freenove Raspberry Pi Pico 2 W Board Pre-Soldered Header, Dual Arm Cortex-M33 and Dual Hazard3 RISC-V Microcontroller, Development Board, Tutorial Example Projects

• Latest Version: Higher core clock speed, double memory, more powerful Arm cores, optional RISC-V cores (compared to the 1 series) (This W version has onboard wireless LAN and Bluetooth)
• Switchable Cores: Allows users to choose between dual industry-standard Arm Cortex-M33 cores and dual open-hardware Hazard3 cores
• Compatibility: Delivers a significant performance boost, while retaining software- and hardware-compatible with the 1 series
• Detailed Tutorial: Provides step-by-step guide with MicroPython, C and Processing (Java) Code (The download link can be found on the product box) (No paper tutorial)
• Example Projects: Each project has schematics, wiring diagrams, complete code and detailed explanations (Need extra items)

$18.95

Buy on Amazon

The official product page is PiJuice Zero from Pi Supply. Check current availability, battery compatibility, board revision and software support before buying.

Raspberry Pi Zero W or Zero 2 W?

For a historically faithful reproduction, use the original Raspberry Pi Zero W. Raspberry Pi lists it with a 1 GHz single-core processor, 512 MB RAM, 2.4 GHz Wi-Fi, Bluetooth 4.1 and an unpopulated 40-pin header; its product page states production is planned until at least January 2030. See the official Zero W specifications.

The Raspberry Pi Zero 2 W has the same 65 mm × 30 mm form factor and broadly compatible 40-pin footprint, but uses a quad-core 1 GHz 64-bit processor, Bluetooth 4.2/BLE and more power. It is a sensible new-build choice if the PiJuice package and historical Python API work with the chosen Raspberry Pi OS release. Mechanical compatibility does not prove software compatibility, and the extra consumption may reduce battery runtime.

Choose a board with a pre-soldered header unless you are prepared to solder the 40-pin connector yourself.

Bill of materials

Core electronics

• Raspberry Pi Zero W, or Zero 2 W after compatibility testing.
• PiJuice Zero.
• PiJuice-compatible 5,000 mAh Li-polymer battery.
• High-brightness LED board, approximately 5 W in the original design.
• Logic-level N-channel MOSFET; the historical build specifies an IRLB8748.
• Current-limiting resistor, originally 0.47 ohm, or preferably a suitable constant-current LED driver.
• Wire, connectors and insulation.

Mechanical and thermal parts

• Heat sink or aluminium mounting plate.
• Thermal interface material.
• Four M2.5 × 4 mm spacers, eight M2.5 × 12 mm bolts, washers and nuts.
• Ventilated enclosure that protects the battery and prevents accidental shorts.
• 8 GB or larger microSD card.
• Reliable 5 V, 2.5 A power supply, subject to the actual load and PiJuice requirements.

How the electrical circuit works

The original design is a low-side MOSFET circuit:

• LED positive connects to PiJuice VSYS.
• LED negative passes through the current-limiting resistor to the MOSFET drain/load path.
• MOSFET gate connects to PiJuice IO2.
• MOSFET source connects to PiJuice ground.

PiJuice I/O 2 applies PWM to the MOSFET gate. The MOSFET switches rapidly, varying the LED’s average current and therefore its apparent brightness. The Raspberry Pi GPIO or PiJuice I/O must not carry the LED’s multi-ampere current. Raspberry Pi documentation recommends limiting an individual GPIO to approximately 16 mA, with a combined GPIO safety figure of approximately 50 mA; the high-current load therefore requires an external switching or driver stage. See the Raspberry Pi documentation.

A MOSFET and resistor are not automatically a precision LED driver. LED forward voltage changes with current and temperature, while battery and system voltage vary during discharge. PWM controls average brightness but does not regulate peak current. A dedicated constant-current driver is the better choice where stable brightness, efficiency, long operating periods or currents above about 1 A matter.

LED selection and resistor limits

The original warm-white LED is approximately 2700 K and rated for a maximum current of 3 A. The project lists 0.47 ohm for its warm-white version, 1 ohm for blue or green versions and 2.2 ohms for red. These values apply only to the specified LED and operating conditions. Do not copy them to another LED without calculating from its forward voltage, desired current, supply voltage, MOSFET drop and resistor power rating.

At 1.6 A, a 0.47 ohm resistor dissipates approximately 1.20 W:

P = I2R = 1.62 × 0.47 ≈ 1.20 W

At 2.1 A it dissipates approximately 2.07 W. A 1⁄4 W resistor is therefore unsuitable. Use a component with appropriate wattage margin and cooling, and measure actual current during commissioning.

Assembly and safety

1. Install the 40-pin header if necessary.
2. Mount PiJuice Zero to the Pi using the spacers and confirm alignment.
3. Connect only a battery compatible with the PiJuice connector, chemistry and charging profile.
4. Disconnect power before soldering.
5. Wire the MOSFET gate, source and drain only after checking the exact device pinout; similar-looking MOSFETs can have different pin arrangements.
6. Connect the LED polarity correctly and include the resistor or approved driver.
7. Insulate exposed conductors and the nearby HDMI connector.
8. Mount the LED on an aluminium heat sink or heat-conducting plate.
9. Keep the Li-polymer battery away from hot components and do not charge it inside a sealed, heat-trapping enclosure.

Never use a swollen, punctured or damaged Li-polymer battery. Provide strain relief, avoid short circuits and do not substitute a random 5 V battery pack without understanding the power path. At maximum output the LED can become hot rapidly; check LED, MOSFET and resistor temperatures during initial tests.

Install Raspberry Pi OS with current practices

The original instructions use an old Raspbian Lite workflow, Win32 Disk Imager, a default pi account and the password raspberry. Do not reproduce that setup.

1. Install Raspberry Pi Imager.
2. Select a current Raspberry Pi OS Lite image and the correct Pi model.
3. Use Imager’s settings to create a unique username and password, set the hostname and configure Wi-Fi and locale.
4. Enable SSH in the Imager settings. Use an SSH key where practical.
5. Write the image to the microSD card, insert it into the Pi and connect PiJuice, the compatible battery and external power.

For SSH, an address such as [email protected] belongs in an SSH client or terminal. It is not a normal browser URL. In a browser, use http://raspberrypi.local/ or the Pi’s IP address, for example http://192.168.1.25/. If mDNS does not work, find the address in the router’s client list or with a network scan.

Install and verify PiJuice software

The historical baseline is:

sudo apt-get update
sudo apt-get install pijuice-base
pijuice_cli

Package names, battery profiles and API behavior can change. Verify the installation method in the PiJuice documentation for your board and operating system. The original project selects the profile PJLIOPO_5000 for its 5,000 mAh battery; select it only if it matches the battery supplied with your build.

Before connecting the LED, confirm that PiJuice is detected, battery readings are sensible and the I2C interface works. Check and log error objects returned by each PiJuice API call instead of assuming every command succeeds.

Install the lighting server

The historical project installs Tornado globally with:

sudo apt-get -y install python3-pip
sudo pip3 install tornado

A safer modern pattern is to keep application dependencies isolated:

sudo apt update
sudo apt install -y python3-venv
python3 -m venv ~/pjlight-venv
. ~/pjlight-venv/bin/activate
pip install tornado

Install the PiJuice Python package using the current vendor-supported method for your OS. The historical program imports PiJuiceInterface and PiJuice; do not assume those imports or methods are unchanged on a current release.

Store the application under /opt/pjlight/ or the application user’s home directory rather than /boot. During testing, use a nonconflicting port such as 8080 and run the service as a restricted user. Avoid making sudo python3 the normal runtime mechanism.

How the original software works

The browser sends brightness values from 0 to 255. The Python code converts that value into a requested current and then into PWM duty cycle:

Rank #2

SANOOV Raspberry Pi Zero 2W Kit

• Powerful Performance: Equipped with a quad-core 64-bit ARM Cortex-A53 processor, the Raspberry Pi Zero 2 W delivers a significant performance boost compared to its predecessor. And built-in Wi-Fi and Bluetooth support enable easy wireless communication and Internet access for your projects, five Times Faster.
• SANOOV Basic Starter Kit for Pi Zero 2 W Include: 1. Raspberry Pi Zero 2 W Board 2.Mini HDMI to Standard HDMI adapter 3.Micro-USB to Standard USB OTG Adapter 4.Aluminum Heatsink 5.40 Pin Header.NOTICE: The kit does NOT include , supply power, case, SD card, keyboard, mouse or monitor.
• SANOOV for Raspberry Pi Zero 2 W features: 1GHz quad-core, 64-bit ARM Cortex-A53 CPU VideoCore IV GPU 512MB LPDDR2 DRAM 802.11b/g/n wireless LAN Bluetooth 4.2 / Bluetooth Low Energy (BLE) MicroSD card slot Mini HDMI and USB 2.0 OTG ports Micro USB power HAT-compatible 40-pin header Composite video and reset pins via solder test points CSI camera connector.
• Video Output & Efficient Cooling: Supports 1080p30 video output via the mini HDMI port, making it ideal for multimedia applications and streaming.The aluminum heatsink helps dissipate heat, ensuring stable performance even under heavy workloads.
• Compact Size: The tiny size of the Raspberry Pi Zero 2 W makes it perfect for space-constrained projects and embedded applications.Ideal for a variety of uses, including IoT projects, home automation, media centers, educational tools, and more.

$119.99

Buy on Amazon

level = int(message.split(':')[1]) / 255

The historical constants include:

CURRENT_LIMITER_RESISTANCE = 0.47
LED_VOLTAGE_AT_1A = 2.95
LED_VOLTAGE_AT_2A = 3.15
MAX_LED_CURRENT = 1.6
MAX_LED_CURRENT_FROM_BAT = 1.5

It configures I/O 2 as push-pull PWM with a 5,000-unit period:

pijuice.config.SetIoConfiguration(2, {
    'mode': 'PWM_OUT_PUSHPULL',
    'pull': 'NOPULL',
    'period': 5000,
    'duty_cycle': 0.1
})

It then applies the duty cycle with:

pijuice.status.SetIoPWM(2, duty_cycle)

The example reduces its current limit from approximately 1.6 A on external power to 1.5 A on battery. These are software values for that project, not guaranteed safe limits for another LED, battery, MOSFET, resistor or PiJuice revision.

For on/off control, the WebSocket handler responds to a TOGGLE message using:

pijuice.power.SetSystemPowerSwitch(2100)
pijuice.power.SetSystemPowerSwitch(0)

The value 2100 appears to be a requested system-output current parameter in the historical API usage. Treat it as an example-specific argument, not a universal PiJuice command.

Web interface and service startup

The original server provides an HTTP page on port 80 and a WebSocket endpoint at /pjlight. The browser sends TOGGLE;LEVEL:<value> for on/off operations and LEVEL:<value> when the slider changes. The JavaScript uses ws://<host>/pjlight for HTTP and wss://<host>/pjlight for HTTPS.

For a local prototype, bind the service to the LAN rather than exposing it to the internet. If remote access is necessary, use authentication and HTTPS/WSS through a properly configured reverse proxy or VPN. Do not leave an unauthenticated root-run control service on an internet-facing port.

The old service file uses /lib/systemd/system/, starts from /boot and includes an uncertain ExecStopPost command. A locally created service belongs in /etc/systemd/system/. A typical deployment pattern is:

sudo cp pjlight.service /etc/systemd/system/pjlight.service
sudo systemctl daemon-reload
sudo systemctl enable --now pjlight.service
sudo systemctl status pjlight.service

Useful diagnostics are:

journalctl -u pjlight.service -e
systemctl is-enabled pjlight.service
ss -ltnp

Use the actual virtual-environment Python path and application directory in ExecStart, and remove the historical shutdown command unless the script demonstrably implements it.

Commissioning checklist

1. Boot the Pi without the high-current LED connected.
2. Confirm network access and PiJuice detection.
3. Verify battery status and the selected battery profile.
4. Test PWM at zero duty cycle.
5. Connect the LED through the correctly rated resistor or driver.
6. Start at the lowest brightness and measure current.
7. Check LED, resistor and MOSFET temperatures.
8. Test on/off and dimming.
9. Remove external power and confirm the battery behavior.
10. Only then test sustained operation and enclosure temperatures.

Battery runtime: estimate, not a result

A 5,000 mAh battery at a nominal 3.7 V stores approximately 18.5 Wh:

5 Ah × 3.7 V ≈ 18.5 Wh

At a nominal 5 W LED load, the ideal LED-only calculation is about 3.7 hours. Real runtime is lower because of conversion losses, Raspberry Pi consumption, driver losses, battery cutoff thresholds, Wi-Fi activity, temperature and battery aging. The Zero 2 W also has higher typical power consumption than the original Zero W, so it may shorten runtime.

For useful measurements, fully charge the battery, record the start time and battery status, run the lamp at 25%, 50%, 75% and 100% brightness, stop at the configured low-voltage cutoff, and repeat each test at least twice. Report measured results separately from the theoretical estimate.

Troubleshooting

The Pi does not boot

Check the image, power supply, battery connector orientation, PiJuice alignment, power-button sequence and possible shorts from spacers, HDMI hardware, solder bridges or the MOSFET. Test the Raspberry Pi by itself before adding the high-current circuit.

PiJuice commands fail

Likely causes include a missing or incompatible package, inaccessible I2C, the wrong PiJuice model, an incorrect Python environment, an unsupported OS release or a missing battery profile. Inspect the returned API error rather than ignoring it.

The LED stays off

Check LED polarity, ground, MOSFET pinout, gate-to-source voltage, resistor continuity, PWM configuration, system-power state and whether the code has set duty cycle to zero.

The LED is too bright or overheats

Disconnect power immediately. Recheck the resistor value and wattage, measure actual LED current, verify MOSFET orientation and PWM polarity, and improve the heat sinking. Do not leave a suspected overcurrent fault powered while investigating.

The page or WebSocket does not work

hostname -I
systemctl status pjlight.service
journalctl -u pjlight.service -e
ss -ltnp

Confirm that both devices are on the same LAN, the service is listening on the expected port and path, the browser uses http:// rather than an SSH-style address, and that HTTPS pages are not attempting insecure ws:// connections. A reverse proxy must also allow WebSocket upgrade requests.

When this design makes sense

Use it for a compact emergency lamp prototype, portable low-voltage lighting, battery-backup experiments or education about PWM, MOSFETs, WebSockets and UPS behavior. It is particularly useful when Linux and local-network control are part of the learning objective.

Choose a dedicated constant-current driver for stable brightness, improved efficiency, long runtimes or sustained currents above approximately 1 A. Choose an addressable LED system for RGB effects and animations. Choose a commercial smart light when you need certification, app and voice integration, scheduling, authentication and unattended household operation.

This is not a mains-lighting design, a certified household product, a weatherproof installation or a complete smart-home platform. It does not natively provide MQTT, Home Assistant integration, cloud access, voice assistants, scheduling or user authentication.

Quick Recap

Bestseller No. 1

Freenove Raspberry Pi Pico 2 W Board Pre-Soldered Header, Dual Arm Cortex-M33 and Dual Hazard3 RISC-V Microcontroller, Development Board, Tutorial Example Projects

$18.95

Bestseller No. 2

SANOOV Raspberry Pi Zero 2W Kit

$119.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.