retiqr

https://github.com/metrafonic/retiqr

I have spent the last couple of days putting together a way to connect to the reticulum network in situations where the only way to access the internet is via some form of internet kiosk. So no wifi, ethernet etc.

retiqr allows you to access the network by bridging a TCP connection via the kiosk browser. Packets are received by your device by visually observing incomming packets encoded as QR codes on the screen. These are decoded and sent to your local rns instance. Packets are transmitted back via an emulated keyboard on an ESP32S3 connected to the kiosk USB port (linked to us via BLE).

Typical throughput: ~~3 kB/s down (QR), ~~500 B/s up (HID). Enough for messaging and Nomad Network.

Let me know what you think! Open to feature requests.

Also check out my guide on running reticulum over DNS (captive portal situations etc)

Holy cow. This is pretty danged cool. What an awesome, and surprisingly effective idea metrafonic :)

Love the name as well :)

It would be awesome to have the camera part running on the ESP32 as well. Not sure if it's fast enough to do the actual QR decoding in real-time, but at least it could just forward to captured images to the host for QR decode there. Then again, QR decode is not too expensive, if I remember correctly, so could probably be done. Then you'd have a self-contained dongle that's easy to place in front of the screen, plugged into the USB port, acting as a full bridge to Reticulum.

Mark wrote:

It would be awesome to have the camera part running on the ESP32 as well. Not sure if it's fast enough to do the actual QR decoding in real-time, but at least it could just forward to captured images to the host for QR decode there. Then again, QR decode is not too expensive, if I remember correctly, so could probably be done. Then you'd have a self-contained dongle that's easy to place in front of the screen, plugged into the USB port, acting as a full bridge to Reticulum.

Thats a great idea! Initially my idea was to use components that people have at home. But i realise now that most people dont have an esp32s3 at home haha, so might as well go for one with a camera! That would be a super smooth setup! Could even try to make it piggyback on the ble interface torlando created.

Damn, what a sick idea. I absolutely love these sorts of off-the-wall projects. Bookmarked for sure.

oh DANG this is really really clever!! That reminds of something adjacent rolling around in the back of my head. I'm gonna clone it and see if I can't hack a lil something, will report back the outcome regardless 🫡

Saw your RRC appearance through retiqr. That was just a great moment to behold :)

oh man I got COMPLETELY nerdsniped by this and went down a few paths haha, let me share:

Core idea: There's a WebHID API in browsers. If you look at caniuse (https://caniuse.com/?search=webhid) it looks a little grim, but I thought, "Most Kiosks in the wild are probably running Windows, and therefore very likely to be running either Chrome or Edge, both of which are where support is quite good!". I figured if you can get through via USB with the HID trick in the first place, then the same kiosk is likely to allow the browser API too.

Three benefits: much higher bandwidth becomes possible, it's a bit more discrete (someone looking over your shoulder wouldn't see a bunch of QR codes. Not a huge deal but just something to note), and the consuming device doens't need a camera anymore either.

Now, because of conditional WebHID support, and quite frankly because the standard QR mode is WAY cooler, the thought was just to provide this as an optional mode to activate via the web page, especially since you need to approve the web page permission dialog for the WebHID anyway.

Got that working on Chrome for my Linux laptop (Chromium from snap didn't play well, but that's not really the target here). Couldn't help myself as I got into the optimziation flow, and got to a point where it was delivering ~300 Kbps goodput, basically bottlenecked by BLE instead.

I saw 300Kbps on a 1M PHY and figured "yeah that's probably near the reaosnable limit". I was about to get that wrapped up and then report back here.... but another thought popped into my head that I couldn't push out:

"Wait, if bluetooth is the bottleneck, couldn't we switch to running this as a WiFi AP? Same 2.4 band, should work great. With any luck, the USB will become the new bottleneck". esp32-s3 is full-speed USB which IIRC is like 10 Mbps PHY but practically probably 4-6Mbps, still a huge step function. Or, worst case, WebHID will have some througput limit and that's our hard ceiling. Worth the test.

I'm assuming something key: In a situation where you'd be doing this anyway, your wifi is probably not being used (if you had a valid AP to connect to with internet connectivity, you'd just use that instead of doing all this). So it seems very well aligned.

AFter sleeping on it, also realized, "maybe Wifi AP would be a really nice convenience factor even in the standard QR mode. We could just connect to our own sovereign little AP, which might make it even more accessible (no desktop BLE client, just a tcp connection). Might be a nice bonus regardless of the fast mode stuff".

Alas, it was indeed WebHID as the hard ceiling, but WiFi AP mode can still get roughly 1.5x the goodput up to that ceiling, which is ~450Kbps

Gonna stop here for now or I'll end up losing weeks to this lmao, but this was such a fun exploration! I'll be sending over a PR, probably later today. If this is just purely antithetical to the project, by all means you can toss it all, no worries. But still wanted to give you that option.

Similar AI Disclosure as you: I'm also a dev by trade, similar YoE, and also used AI tooling throughout this.

PS: I could probably swing a lil dedicated server to run the backend side for the community to tinker with too, if you want. Just let me know!

tl;dr: Two new modes. For the transport mode, standrd qr or fast. For the user-side link, BLE or WiFi AP. ~~300 Kbps goodput in fast + BLE, ~~450 Kbps in fast + WiFiAP. Preparing PR and expect to have it submitted at some point today. Screenshot of using it on my machine: https://i.postimg.cc/0jKvB1f4/Screenshot-from-2026-05-23-13-16-21.png

Holy cow I'm happy with how this has come along (just couldn't help myself, had to add a little more). I have some more to share which I think everyone here will really like! But just to bury the lede for a moment, I also want to make sure image uploads work correctly here real fast before I write up the rest. So to tease it a bit as well as test:

Alright! so as you can see, the web page allows you to configure the dongle as well. You can flip between bluetooth and wifi, and on wifi set the ssid and password to your choosing. (Note right now this is still designed for single-session links; I'm noting that in the PR for high value future work to make it multi-client, so everyone in the area can benefit if they know the creds!).

First up, showing that I see that valid hotspot on my phone, there it is! 'flybywifi' according to my settings on the web page.

And showing/proving it's not a real wifi connection, no internet. (Also note if any of you do this, make sure to check the box and say yes; won't work until you do).

With that all set up, I opened up the fantastic Columba app and added a TCP client as normal

The host and port are still hard-set for now, to these values

Here you can see it's active, and it's the only interface active

First moment of truth... before /after hitting announce:

There it is! Data's flowing from my phone!

(Will continue; trying to keep these messages broken up in case too many image uploads cause issues)

Oh sorry short sidebar to clarify my setup: I have a powered USB hub, the red cable is the one connected to my Heltec V4, which is my would-otherwise-be-RNode-but-is-flashed-for-this. so that USB link is what's talking to the WebHID interface and the onboard S3 is running the AP (sorry sx1262, you get to rest for now).

Ok back to the fun stuff. With Reticulum now running on my laptop, with only the local socket listening to the web server from retiQR, the two should be able to talk. And sure enogh, there's two announces flowing in the data, and you can see the Sideband app on my Laptop sees the announce (another before/after):

To isolate the other side real quick, here's sideband firing an announce and the green rx side showing hte data hit.

And here's Columba showing the announce!

Alright, smoke test is good, concept proven. Now the fun part: moving some real data over this thing (coming in next post)

Clean convo history for clarity. Before:

After:

Messages sending! I figure we ought to see some larger data move though, to help show the bandwidth we're working with here:

(note the displayed bitrate above wasn't really the complete picture yet because we only sent a short text. Remember that, I'll come back to that in a sec). Anyhoo, latest picture was of my washer, so I figured it's as good as any to fire over

Success!!!! A nice medium quality image firing over what felt like effectively immediately, from when I hit send to when it showed on the laptop's Sideband.

Also here was a cat of my reticulum config, showing the settings and also showign/proving it was the only live interface

I figured let's push it a bit, so I bumped the quality up to send it again. PLUS, note here how now the bitrate shows our real effective limit after that first image sent

Just showing the size before send, ~330KB.

So this one took the ~10 seconds it estimated.

Then, after compltion, the confirmation it all sent, plus the data bars in the background showing all that time it occupied (and the asymmetry where one side is sending a large file and one isn't)

Including this one as well just to clearly see some of metrics showing on the page

Then with my laptop as a transport node, I connected to a few community gateways, and now you can see Columba on my phone showing those distant announces now

Here's the interfaces again and some more announces:

To wrap this up, I fired an announce out there on those community nets; if you saw "Ken a.k.a. Frosty" then that was me! (LXMF destination hash a6ac...62a2). Feel free to say hey, I'll leave this up and running for a little while now.

Thanks for letting me flood this thread for a moment. This was cool as hell to work on. THanks again to metrafonic for such an AWESOME idea and a great baseline to build on. I'll get that PR over to ya shortly

OH, quick followup! The fast mode can be toggled on/off and even in realtime. You can see here where I turn it off, then the general flow (with the cool as hell QR code system flowing behind it as everything stays connected)

Then finally just showing now I've approved the dialog and switched back to fast mode, it keeps goin.

PR submitted! available here: https://github.com/metrafonic/retiqr/pull/1

Okay lmao I - yet again - couldn't help myself. Got a little deploy running with this. Anyone can grab the firmware from my fork/PR if you want to try it fully. But even if not, you'll still get a nice "visual downlink" of QR codes flowing through:

https://retiqr.up.railway.app/

It's pointed at spicy.hellfirehacking.club:4242 just because it had good reliability and recency based on https://rns.wirebase.org/

If there's a better or more preferred node just lemme know!

PS: Also made it a template on Railway, so anyone else can deploy one pretty quick and easy. Bus factor, and all that. (right now it's pointed to my fork & branch, but if PR is merged I'll point it back at upstream)

https://railway.com/deploy/6hrAMZ

Hey @KenAKAFrosty
What a great idea with the WebHID fast mode! I also really love the wifi connection part, as now we have a way to make it work without a client side app, just a simple TCP setup making phone setups work too!

Ive also been thinking about changes on the gateway side. If it is possible to let the user choose which reticulum tcp endpoint they want to uplink to, instead of having it set at startup. Im thinking of starting with a dropdown of predefined server-port combos first as there are some security concerns in allowing the bridge to connect to anything.

I am eager to merge in your changes. I think having a toolbox of multiple ways to connect is a killer feature!
Ill do some testing today and hopefully get it done by the end of the day (European time).

I also think a public online instance is a good idea. I was thinking of running it on an oracle free-tier instance i have, but if you have other good hosting alternatives we can look at that too. If you are comfortable with it then i could add your current link as a demo link on the main readme so people can try it out.

Again, awesome work! I love how fast we can go from idea to implementation.

metrafonic wrote:

Hey @KenAKAFrosty
What a great idea with the WebHID fast mode! I also really love the wifi connection part, as now we have a way to make it work without a client side app, just a simple TCP setup making phone setups work too!

Ive also been thinking about changes on the gateway side. If it is possible to let the user choose which reticulum tcp endpoint they want to uplink to, instead of having it set at startup. Im thinking of starting with a dropdown of predefined server-port combos first as there are some security concerns in allowing the bridge to connect to anything.

I am eager to merge in your changes. I think having a toolbox of multiple ways to connect is a killer feature!
Ill do some testing today and hopefully get it done by the end of the day (European time).

I also think a public online instance is a good idea. I was thinking of running it on an oracle free-tier instance i have, but if you have other good hosting alternatives we can look at that too. If you are comfortable with it then i could add your current link as a demo link on the main readme so people can try it out.

Again, awesome work! I love how fast we can go from idea to implementation.

Thanks for the kind words! I'm sure there will need to be some tweaks and fixes still, this is just a starting point for all of us to work off of, so I appreciate your being so receptive to it!

As for putting the link as a demo on the main README: absolutely! Good thinkin. You can also include this snippet: [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/6hrAMZ)
which looks like this:

to also make it really easy for others to spin this up (resiliency in mind).

Ah, parallel thinking.
Video calling is likely a very robust channel.
I was struggling with the bidirectional problem. It is easy to flag for unusual traffic.
I would also like to point out the broadcast possibilities. A livestream could anonymize destinations (channel would need to be established out of band)
Also full duplex across providers could represent significant bandwidth and difficult to correlate. (Live stream rx, video call tx)
I think these Webcam modems (and audio) are extremely important. These Communication channels are always going to exist in some form for normal use. Stenograpicly layering data over actual video (man in the middle pi re encoding Webcam input?) May not even be detectable.