My Contribution to LEDE (OpenWrt): A Hacktoberfest Adventure
Hacktoberfest is a free-shirt-incentive-based-event for open source software contributions. It is quite simple - if you open four pull requests during October, you’ll get a free shirt. Since developers love swag, it’s pretty effective.
This Hacktoberfest, I was surprised to find myself contributing to LEDE: Linux Embedded Development Environment. LEDE is a fork / spinoff of OpenWrt, which is a Linux distribution for embedded device. In short, it provides aftermarket firmware for routers.
Story Time
A few weeks ago, I bought a TP-Link Archer C7 router. Routers are one of those devices that always suck, regardless of how much you’re willing to pay for them (second only to printers). The thing about routers is that the hardware is fine - it’s the software on top that’s an afterthought. My experience is that combining quality router hardware with great software makes the overall performance of routers immensely better. Since I intended to flash an alternative firmware immediately, I made sure that it is supported by OpenWrt before I ordered it. When I received it, I eagerly opened the box, connected it to my laptop and proceeded to flash OpenWrt. Except, it didn’t work.
Error Code: 18005
Upgrade unsuccessfully because the version of the upgraded file was incorrect. Please check file name.
Errr… what’s going on? OpenWrt is confirmed to work on this router! So I searched online, and it appeared that TP-Link has a new region-locking mechanism that prevents firmware upgrades from different regions. Searching online, I found that the LEDE project seemed to fix this problem, as it offers three different variants of the firmware for my router:
lede-ar71xx-generic-archer-c7-v2-squashfs-factory.bin
lede-ar71xx-generic-archer-c7-v2-squashfs-factory-eu.bin
lede-ar71xx-generic-archer-c7-v2-squashfs-factory-us.binUnfortunately, none of those work for upgrading my router. At this point, I was kind of desperate. Why won’t developers also provide firmware for the IL (Israel) region?
Wait a minute, I’m a developer!
So I searched in the LEDE Github repo for the “factory-eu” suffix. Then, I used “git blame” to find the commit that added it. Fortunately, it was a simple commit with a detailed commit message:
ar71xx: generate US- and EU-specific images for the Archer C7 v2
TP-Link has started providing US- and EU-specific stock firmwares that only
allow upgrading to firmwares with the same region code. Provide factory
images for both these regions.
To avoid confusing users outside these regions, we still provide a
"universal" factory.bin without a region code, although flashing either of
the US and EU images would work as well.
Signed-off-by: Matthias Schiffer <mschiffer@universe-factory.net> BOARDNAME := ARCHER-C7-V2
DEVICE_PROFILE := ARCHERC7
TPLINK_HWID := 0xc7000002
- IMAGE/factory.bin := append-rootfs | mktplinkfw factory -C US
+ IMAGES := sysupgrade.bin factory.bin factory-us.bin factory-eu.bin
+ IMAGE/factory-us.bin := append-rootfs | mktplinkfw factory -C US
+ IMAGE/factory-eu.bin := append-rootfs | mktplinkfw factory -C EU
So the solution was pretty simple - right? Just clone the repository and add a factory-il file to the Makefile. Except, after many hours of compilation, it didn’t work. There apparently is no IL region.
We’ll, I’ve always relied on the kindness of strangers. So I just point-blank asked the committer for help.
I was surprised to see the effort that Matthias had put in to help me. He held my hand further by helping me with my Pull Request until I got my router to boot with LEDE and eventually become fully functional, with QoS, web interface and all the other great LEDE features. A few more tweaking to my commit and it was merged into the LEDE repository.
If you look in the right place, you can see my labor of love available as nightly snapshot artifacts:
Conclusion
In the end, the changes I needed to make were just a few lines long, but I can’t imagine succeeding without help from someone intimate with the project. Matthias was an epitome of how open source maintainers should behave. As an open source maintainer myself, this has made me more aware of how new contributors might feel when they ask for help.
My advice from this experience is this:
For new contributors: I know you’re afraid you might be out of your league. You know something? You might be right. That’s why the term “open source community” exists. We’re a community, and we help each other out. Don’t be afraid to ask for help. You’ll be surprised at the efforts others will make, if you just ask.
For maintainers and contributors: Remember that tasks that seem trivial to you might be insurmountable obstacles to newcomers. Taking that extra few minutes to help can prevent a newcomer from giving up. It will be as satisfying for you as it is for them, and you will have grown your community, one developer at a time.
Follow me on Twitter and Facebook
Thanks to Hannan Aharonov and Ram Rachum for reading drafts of this.