OrangePi Zero 2W Implementation

[nagolnad]

The utility of this repo is understated for those of us using HomeKit / HomeAssistant / HomeBridge. Many thanks to @kormax and anyone they drew inspiration from for this project.

I came across this on printables here but the creator of the case didn't provide too many details on how to get it running. I am creating this to fill in some gaps on an implementation between what is available with the two projects and as a reminder in case I want to do this in the future. I have created three of these successfully. The first one had a lot of trial and error but the second two took a fraction of the amount of time. This is not an entry level project so if you don't have some basic experiences with electronics, soldering, 3D printing, linux, and Apple Home (maybe Home Assistant too), then I would not suggest tackling this unless you are ok with working through some frustrating things. Having said that, it's a pretty cool set of projects that enable this post.

You will need:

• A OrangePi Zero 2W or other Zero form factor equivalent. link
• An SD card >= 16gb. These seem to perform pretty well for me. link
• Mini HDMI to HDMI adapter link
• A PN532 NFC reader. Ordered three of these and all three worked. link
• A USB cable and power supply for the 5V connection. You will need a USB-C cable to power the Pi initially. You may also want a different cable you can cut the end off to supply the VIN pin if you are printing the case. I used an USB A with a mini end I had lying around.
• A keyboard you can connect to the PI with using USB-C
• Some wire, I used various lengths of silicon wire
• Soldering iron and basic skill (this is on you, practice makes better) to solder the wire to the pinout pads.
• Any of the misc hardware and materials from the printables post as you see fit if you are using his case.
• Optionally two Wago connectors for easily connecting power to the Pi.

Start with going out to the OrangePi site and reviewing the pinout diagram. You will want to click the downloads tab and download the official Debian image. I also suggest downloading the user manual. The site has been inconveniently down a few of the times I needed some information off their wiki. The user manual has any of the reference material we might need.

Download and install balenaEtcher link. Follow the normal instructions for burning the Debian image to the SD card. You can choose to use another application if you are familiar but balenaEtcher is easy.

Insert the completed SD card in to your Pi. Plug in your monitor adapter, the monitor, the keyboard, and power to the pi. Some lights will start flashing as the Pi boots and you should see a stream of text show up on the monitor. If everything went well, the Pi will auto login to a terminal under the default user "orangepi"

First thing is to do a some setup and housekeeping.

Run orangepi-config. This will start the Pi configuration menus. The escape key returns you to the prior menu.

Start with 'Network'. On the next menu choose 'Wifi' and connect the Pi to your local wifi. It will display to your the SSIDs it finds and ask for a password. When connected it will mark the connection with an asterisk. Return to the main menu.

Next select 'System'. Choose 'Firmware'. When asked if you want to update the firmware select 'Yes'. It will likely ask you to reboot, which you should allow. Wait for the Pi to reboot and start up orangepi-config again.

Enter in to the 'System' menu again. Choose 'Hardware'. We will need to enable one or more UART pins. They are disabled by default. I chose to enable all five that are on the board but I only used UART5, which is what I will reference later. Enable 'ph-uart2', 'ph-uart5', 'pi-uart2', 'pi-uart2', 'pi-uart3', 'pi-uart4'. Choose 'Save'

This these two are optional. While in 'System' turn on 'Avahi' and the 'Zsh Shell'.

Return to the main menu. Choose 'Personal'. Select 'Timezone' and walk through the prompts to select your timezone. On the 'Personal' menu you can also choose to change the 'Hostname' of the system. I chose to to use the name of my door and 'homekey' concatenated together so I could easily identify them on my network. If you can see a list of devices in your router it should be easy to find the IP address of your Pi. Double check this is the case. This will be important later because once you have buttoned up the Pi and reader in a case, you will want to SSH to it for future updates.

Exit out of the orangepi-config program. Reboot the Pi by typing sudo reboot now. It is going to ask you for a password, which by default is orangepi. When you hit enter the Pi will start rebooting within 30 seconds. Wait until it finishes and brings you back to the orangepi user prompt.

There are a few more housekeeping items to complete at the terminal. I am pretty sure the order doesn't matter but depending on how you complete them, some of the behavior may be different.

Start by turning off the auto login. This is done with this command sudo auto_login_cli.sh -d. It will not confirm it did anything.

Next change the password of the orangepi user. This is done with this command passwd. It will ask for the current password, which is orangepi, then your new password, and a confirmation of your password . Your choice on the new password but keep in mind this device is a small, full functioning computer, connected to your wifi and it is likely in a spot that is visible and unsecured relative to your home. READ: you want a password that cannot easily be guessed or cracked should the device disappear from your home.

Reboot the Pi. You should be greeted with a username prompt that will ask you for a password. We are not going to use the orangepi user from this point forward. There are two users on the Pi, 'orangepi' and 'root'. We are going to use the 'root' user going forward.

Login to the Pi with the user root and the password orangepi.

Repeat the command passwd to change the 'root' password to your chosen password. It will only ask for the new password and confirmation in this case. Type logout and log back in with root and your chosen password.

A little more housekeeping.
Run
apt update
apt upgrade
Seems that on the OrangePi there are some broken packages so you may have to run apt --fix-broken install and then apt upgrade again.
That will bring the Pi up to date on the software side.

I would stop here and get the soldering out of the way. Shut down the Pi with the command shutdown now. A bunch of text will flash on the screen until the Pi has completed its shutdown processes. You can unplug all the connectors from the Pi.

A picture of the pinout is on the OrangePi Zero 2W site link

Looking at the pinout picture, on the right side row of pins, I soldered wires to the two 5V pins and the first and second GND pins. On the left side of pins, I soldered wires to the UART5_TX (PH2) and UART5_RX (PH3).

The pin pads on the PN532 NFC reader are marked on the back side for power (vcc), ground (gnd), txd, and rxd. Solder one of the 5V power wires to vcc, one of the GND ground wires to gnd, the UART5_TX wire on the Pi to the rxd pin pad on the PN532, and the UART5_RX to the txd pin pad on the PN532.

Double check all your solder joints. Weird things will happen if any of them are not well connected and you will chase issues down for hours.

Once you feel good about your connections go ahead and connect your Pi back up. The red LED on the PN532 should be lit up if you are getting power to the board. Everything is pretty straight forward from this point.

Log back in to the Pi as the root user.

Clone this repo using git clone https://github.com/kormax/apple-home-key-reader.git. It will create a directory called apple-home-key-reader. Enter this directory using cd apple-home-key-reader.

Follow the installation steps one and two.
python3 -m venv ./venv
source ./venv/bin/activate
python3 -m pip install -r requirements.txt

If you are using an orangepi and these these instructions, you can use the following for your configuration.json. You can edit it using nano configuration.json

{
    "logging": {
        "level": 20
    },
    "nfc": {
        "port": "ttyS5",
        "driver": "pn532",
        "broadcast": true
    },
    "hap": {
        "port": 51926,
        "persist": "hap.state"
    },
    "homekey": {
        "persist": "homekey.json",
        "express": true,
        "finish": "silver",
        "flow": "fast"
    }
}

The only thing changed in it is the 'port' value. ttyS5 is the port for UART5 pins we enabled and soldered the PN532's TX and RX pins to.

Start the application with python3 main.py. You will want to pay attention to the output. The HomeKit pairing key will be displayed early in the log output. If you are seeing errors at this point you can think about a few things. 1) check the solder connections again, specifically the tx an rx on each board. Make sure you chose the right pins. It is easy to be off by one. 2) on the orangepi-config, double check to make sure you enabled the UART5 pins. 3) reboot the Pi. I had to do this at various times through the process.

If you are not seeing errors and see the HomeKit pairing code, you are ready to add it to your Home in the Home app. Have your phone in close proximity to the PN532 (it doesn't have to be touching) Start up the Home app and chose the plus in the top right. On the menu, choose 'Add Accessory'. The popup screen that is displayed will not help so you need to choose the 'more options' link at the top. You should see a device labeled something like 'NFC ' or something similar. Clicking the device won't help so you will need to click the 'My Accessory Isn't Shown Here' button. On that menu is the option to 'Enter a setup code'. Choosing that option will bring up a box that you can enter the HomeKit pairing code that is displayed in the log of your Pi's output after running the program. Enter the code and click 'Continue' on your phone. If all goes well you will see messages flash by on the Pi's output as it all the things that kormax has setup. Once this has completed your phone will ask a few more questions before finishing up adding the HomeKey to your home.

At this point you should be able to hold your phone close to the PN532. If the HomeKey activates you will feel the haptic and see the HomeKey displayed in the Dynamic Island. Tapping the PN532 will toggle the lock between on and off in the Home app.

Almost done. You will need the application to start automatically when the device is plugged in and boots up. This is done using systemctl.

To create the service that does this type nano /lib/systemd/system/homekey.service on the Pi's terminal.

Paste the following in to the editor.

[Unit]
Description=HomeKey
After=multi-user.target
Conflicts=getty@tty1.service

[Service]
Type=simple
WorkingDirectory=/root/apple-home-key-reader/
ExecStart=/root/apple-home-key-reader/venv/bin/python3 main.py
StandardInput=tty-force
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

Save the file with 'ctrl-x' and 'yes'

In the terminal type the following.
systemctl enable homekey.service
systemctl start homekey.service

This will register the service with systemctl and start it. Reboot the Pi at this time. The service did not start correctly for me until I did.

After the Pi has finished rebooting, you log back in, you can type systemctl status homekey.service You should see some output similar to this

● homekey.service - HomeKey
     Loaded: loaded (/lib/systemd/system/homekey.service; enabled; preset: enabled)
     Active: active (running) since Sat 2024-01-20 22:51:10 EST; 12h ago
   Main PID: 1497 (python3)
      Tasks: 2 (limit: 4546)
     Memory: 23.7M
        CPU: 48min 44.274s
     CGroup: /system.slice/homekey.service
             └─1497 /root/apple-home-key-reader/venv/bin/python3 main.py

You can tap the PN532 with your phone and you should see/feel the lock toggle action as the HomeKey is activated. If you have an Apple Watch or share you Home with someone else, they should also have access to the HomeKey.

In a commercial product this action will unlock or lock the physical lock. Here you have to perform an extra step. In my use case, I wanted to the HomeKey to action my already installed HomeKit lock so I created a simple automation action in the Home app that triggered my lock to unlock when the HomeKey unlocked and reciprocal actions when it locked. In theory, you can have it do anything your home automation is capable of doing. For HomeAssistant users, make a note. This was a little confusing for me first trip around. If you have HomeBridge installed, do not pair this HomeKey with it. If you go in to HomeAssistant prior to pairing it with your phone, it will show up as a new device but when you pair, it will not actually create the HomeKey in your Home app. There are a number of methods you can use to get HomeAssistant to respond to your HomeKey's toggle action but registering directly to HomeAssistant via HomeBridge is not it. If you are not toggling a physical lock that HomeAssistant can see you can create a virtual switch in HomeAssistant that HomeBridge can see, allowing the HomeKey to toggle it, for example.

To wrap it all up, I cut the mini-usb end of a USB-A cable I had lying around and striped the pos and neg wires. I used the Wago connector to connect the USB power to the second set of power pins I soldered wires to.

Even following these instructions, there are still a plethora of things that can be wrong or mis-configured if it doesn't seem to be working for you out of the box. In my trial and error I had address the following areas, you may as well.

• Bad solder joints
• incorrect UART pins used. You cannot use UART0 as it is reserved for debugging.
• UART pins not enabled in config
• not creating the venv in the apple-home-key-reader directory
• not having a 'WorkingDirectory' specified in the service section of the homekey.service file.
• trying to update the Pi firmware without connecting to wifi first
• not realizing that /dev/ttyS5 is UART5 and reading it on the screen as tty55. If you choose another UART pin, your port in /dev/ will be ttyS

Generally speaking I think these instructions should work for any Pi Zero device. I chose the Orange Pi based on availability and price and the fact it had a 4GB of RAM model. The configuration or pinout may be different but if it is using an Debian based image, most of the commands and processes should translate.

I may edit this post if I have corrections but don't count on me being real responsive to any particular issue or situation. These instructions worked for me and are provided as-is.

[kormax]

Awesome!

Thanks for this info. I think that many people will appreciate this tutorial, most parts would be useful regardless of specific SBC.

[peterrakolcza]

Really great tutorial! I have been looking for a similar solution for a long time now!!

I have 2 question in my mind:

• I have a Homebridge instance running, but I do not use HomeAssistant. Is this configuration will cause any issues?
• Can I modify the python code to for example make HTTP requests when opening/closing the virtual lock?

[kormax]

1. When you run the project it exposes a lock through HomeKit directly. There's no direct dependence on HomeBridge or HomeAssistant.
2. Yes, you can add your own logic, including HTTP requests and etc. The method I propose to use for that is on_endpoint_authenticated, as it gets called when a device authenticates via NFC successfully.

[peterrakolcza]

Thanks for your reply!

After going through a code a little bit, I feel I do not understand everything properly. What is the difference between the service.py and accessory.py file?

I have created a Smartlock which uses HTTP requests. It can do 2 things: lock or unlock door and get the current status. I want to poll for the status of the lock regurarly and send a lock/unlock HTTP request depending on the current state of the lock when a device authenticates via NFC successfully. However, I do not know which functions or files to use. I read that the accessory.py does not implement any logic, just forwards everything to the service... why is that?

My initial impression is that this should not be hard to implement, I just do not know which functions to delete/append with my logic. Any help is appreciated.

[350d]

Awesome tutorial! Thanks! I will make it work on my HomeKit setup ASAP! All components ordered already.

[aesterling]

Great write-up @nagolnad! Can I use an old Raspberry Pi 3 B+ for this and still follow your instructions, or does it need to be a zero form factor version?

[nagolnad]

Some of the specific commands that are related to the OrangePi would need to be tweaked but most of it would be similar or the same I would assume.

[aesterling]

Thanks - will give it a try!

[aesterling]

Just set this up using an old Raspberry Pi 3 B+ and it works great. Thanks!

[nikowebber]

[kormax]

Sadly, I am unable to test your case, but to me "No Response" looks like an issue with the local network. Either there's no link from home hub/device to the "lock", or there's a problem with the router.

You can verify that the code itself starts by observing the NFC reader/uart adapter, as it should start blinking (indicating tx/rx activity).

[nikowebber]

Thank you for your response.
My issue is that when I reboot the Pi it doesn't seem to restart the application, 'python3 main.py'.

I really do appreciate your help.