Skip to content

Getting started

Jump to bottom
ius edited this page Jan 30, 2025 · 7 revisions

Prerequisites

Required

  • ZBMINIR2
  • Linux machine (any distribution, virtual machine is okay too)
  • Any SWD adapter/debug probe supported by OpenOCD - must be able to supply 3.3V.
    • Recommended: "J-Link" OB ARM (Aliexpress, Amazon) is used in this guide ¹
    • Do not use a ST-Link clone: these rely on the hla_swd backend which doesn't work...
  • Soldering iron or probe kit (PCBite thoroughly recommended)

Optional

  • 3.3V USB-to-serial adapter (needed for debugging)
  • ZB-GW04 Zigbee dongle for OTA updates/debugging ²

¹ Multiple revisions of this adapter exist - some have micro USB, others have USB C. The USB C one does not work with a USB C/C cable - use a USB A/C cable!

² Zigbee brokers like Zigbee2MQTT/ZHA also support OTA - using an EZSP dongle offers more control over the process and is documented here

Warnings

  • You cannot revert to the stock firmware after wiping the device.
  • DANGER: do not connect the device to mains voltage unless it's fully reassembled and debug adapters have been removed. ZBMINIR2 uses a capacative dropper DC power supply - as a result the 3.3v and gnd pins may be at ~230V referenced to earth. Avoid hurting yourself or your computer.

Software preparation

Building the firmware requires various Silabs utilities, while flashing needs a patched version of OpenOCD with support for Silabs EFR32 series MCUs.

  1. Install the Nix package manager by following the official documentation. If your distribution provides a package for nix that will likely work as well.
  2. Clone the repository and run nix-shell nix/shell.nix. Nix will download and install/compile all required packages and dependencies. You will end up in a shell environment with all necessary utilities present. Re-run the command at a later moment in time to re-enter the shell or to spawn additional shells.
  3. Run ./build.sh to build the firmware. It should produce various build artifacts in the build directory - notably zbminir2_full.bin for the main firmware + bootloader combined.

Attaching the debug probe

  1. Disassembly is easy. Use your nails to separate the top and bottom. Remove the housing. There's a thermal (?) pad on top of the relay which you may want to remove temporarily in order to avoid damaging it.
  1. Flip the device over to its side to find the MCU board.
  1. Connect all marked test points to your debug adapter. Solder them or use something like the PCBite probe kit for a very convenient temporary setup.
Board Adapter
3V3 VCC
GND GND
CLK SWCLK
DIO SWDIO

Unlocking

  1. Run OpenOCD passing the adapter/interface specific configuration file for your debug adapter (-f interface/jlink.cfg) and target configuration file (-f openocd/efm32s2.cfg). Press CTRL+C to quit.

Important

OpenOCD needs to be able to access your debug adapter. The recommended approach is to create a udev rule for the adapter:

/etc/udev/rules.d/99-local.rules:

SUBSYSTEMS=="usb", ATTRS{idVendor}=="1366", OWNER="myuser-changeme", GROUP="mygroup-changeme"

Alternatively, you may choose to run OpenOCD as root

If you have everything setup correctly, output should look like:

$ openocd -f interface/jlink.cfg -c 'transport select swd' -f openocd/efm32s2.cfg
Open On-Chip Debugger 0.12.0+dev-snapshot (2025-01-02-17:41)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
swd
efm32s2_dci_read_se_status
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : J-Link ARM-OB STM32 compiled Aug 22 2012 19:52:04
Info : Hardware version: 7.00
Info : VTarget = 3.300 V
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x6ba02477
Info : SWD DPIDR 0x6ba02477
Error: Failed to read memory at 0xe000ed00
Successfully connected to DCI
DCI SESTATUS response:
Debug lock (config): Enabled
Device erase: Enabled
Secure debug: Disabled
Debug lock (hw status): Enabled


 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  You will not be able to communicate with this device
  unless you perform a device erase (if available, indicated above)!
  Try efm32s2_dci_device_erase to attempt erase.
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


Warn : target efm32s2.cpu examination failed
  1. The MCU is debug locked and needs to be erased before being able to flash it:
$ openocd -f interface/jlink.cfg -c 'transport select swd' -f openocd/efm32s2.cfg -c 'init; efm32s2_dci_device_erase'
...
Successfully connected to DCI
Device erase command sent. Device should now be erased and debug should be available again after a reset
  1. OpenOCD should now be able to connect:
$ openocd -f interface/jlink.cfg -c 'transport select swd' -f openocd/efm32s2.cfg 
...
Info : J-Link ARM-OB STM32 compiled Aug 22 2012 19:52:04
Info : Hardware version: 7.00
Info : VTarget = 3.300 V
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x6ba02477
Info : [efm32s2.cpu] Cortex-M33 r0p3 processor detected
Info : [efm32s2.cpu] target has 8 breakpoints, 4 watchpoints

Flashing

  1. Flash the zbminir2_full.bin file to the device using OpenOCD.
$ openocd -f interface/jlink.cfg -c 'transport select swd' -f openocd/efm32s2.cfg -c "program build/zbminir2_full.bin 0; reset; exit"

Open On-Chip Debugger 0.12.0+dev-snapshot (2025-01-02-17:41)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
cortex_m reset_config sysresetreq
Info : J-Link ARM-OB STM32 compiled Aug 22 2012 19:52:04
Info : Hardware version: 7.00
Info : VTarget = 3.300 V
Info : clock speed 4000 kHz
Info : SWD DPIDR 0x6ba02477
Info : [efr32.cpu] Cortex-M33 r0p3 processor detected
Info : [efr32.cpu] target has 8 breakpoints, 4 watchpoints
Info : starting gdb server for efr32.cpu on 3333
Info : Listening on port 3333 for gdb connections
[efr32.cpu] halted due to debug-request, current mode: Thread 
xPSR: 0xf9000000 pc: 0x00000138 msp: 0x20001008
** Programming Started **
Info : detected part: MG21A020, rev 49
Info : flash size = 768 KiB
Info : flash page size = 8192 B
Warn : Don't know EFR/EFM Gx family number, can't set MSC register. Defaulting to EF{M,R}xG22 values..
** Programming Finished **

Use

Remember to disconnect your debug adapter and reassemble your device before hooking it up to mains voltage.

  1. Join the ZBMINIR2 to an (open) Zigbee network by pressing the physical button. You can also trigger a (re)join by toggling the external switch ~10 times in rapid succession.

  2. Bind the ZBMINIR2 On/Off cluster to a target device, e.g. a lightbulb. Operating the external switch should send a Toggle command to all bindings.

Development hints

  • Connect a 115200 8n1 UART to the TX/RX pads to access the embedded command line interface - very useful for debugging/development.
  • The switch_event_handler function in app.c sends the On/Off cluster Toggle command to all bound devices. It contains (commented out) examples of sending other commands (such as On/Off or Move to Level with On/Off) instead.

Clone this wiki locally