ImSwitch-OS Onboarding: first-run flow, networking, Tailscale, config & landing page

[beniroquai]

This project is tracked on Notion at https://www.notion.so/First-Time-FRAME-Customer-Onboarding-UX-iter-1-2774e612c78a8086a5b6ff70cf8bfff9?source=copy_link

---

Together with @ethanjli and @gokugiant we have been discussing the best strategy on how to interact with the microscope the first time. Based on valuable feedback from @Mikrodoktor we have probably identified a rough first milestone for our project: See an image through the webinterface and change necessary configurations on the way
Below I formulate the issue and/or necessary steps to reach this goal. It's all very vaguely formulated. The Drawio file for the graph can be found here.

The documentation could/should live here? https://github.com/openUC2/openUC2.github.io/blob/master/docs/05_ImSwitch/01_Quickstart.mdx

So, we want tomplement the end-to-end onboarding for new customers unpacking a FRAME microscope. Users should reach a landing page via LAN or Wi-Fi, configure networking, Tailscale, ImSwitch, updates, and file presets with safe rollback.

Diagram

Scope & Owners

• Frontend/Backend (ImSwitch UI + API, config wizard, update UI, presets, firmware trigger) => I guess @gokugiant
• OS image, networking stack, captive portal, DHCP/DNS, Tailscale, services, persistence, security => I guess @ethanjli
• Testing and complaining: @Mikrodoktor

...but we will learn on the way ;-)

I think the Configuration is shared: @gokugiant you probably provide the schema/UI + API from the ImSwitch/React side and @ethanjli provides storage location, defaults, docker integration, updates through forklift and systemd services.. ?

User flow

I can imagine to have the following pathways:

1. LAN => discover device => open IP => Landing Page (discovery either our installer imswitchinstaller/main.js at main · openUC2/ImSwitchInstaller or something like angryipscanner?)
2. Wi-Fi => see SSID => connect with PW (youseetoo) => captive portal opens automatically (?) (fallback to IP) => Landing Page

Landing Page cards: Open ImSwitch, Network, Computer, Updates, Files, Tailscale. (@ethanjli you have started that already in the pallet repo https://github.com/openUC2/pallet/

Deliverables

These are some random points that we should discuss! Please complain/change anything :)

App (ImSwitch) @gokugiant

• Config Wizard (first-run + re-run)
• Connect to nearby Wi-Fi (via API to OS) (=> WifiController.py)
• Restore config from file / Fallback
• Show current config + validation in the GUI maybe through the ConfigWizard
• “Safe apply” with auto-rollback on failure - maybe check config for validity/integrity?
• ImSwitch settings pages for:
  • API/backend settings (host, ports, HTTPS off/on, tokens)
  • Camera, stage, modules; persist via common config store => I think this would be a dreamm..have a page of any of the components in the microscope and have a dropdown to customize the settings - maybeintegrated via the youseetoo.gihtub.io/configurator at one point :) Some inspriation here https://www.nature.com/articles/s41592-021-01315-z (Actually REACT based)

• Files UI (already existing - mostly for images/videos captured with microscope, no OS stuff - has to be served through docker mounts)
• ImSwitchConfig rework
  • “Single source of truth” indicator (which node stores master config); how is it loaded, CLI vs python main.py vs. Docker - where do we store it?
  • Sideload config via USB drive?
• Error handling: toast + details, retry, copy diagnostics.
• Telemetry/logging: structured logs for onboarding steps.
• Docs: short first-run guide with screenshots.

OS/Networking @ethanjli

• Landing Page (web) with cards linking to modules below.
• Base image with services (systemd) and health-checks via forklift
• Networking modes
  • Wi-Fi STA connect (from API)
  • AP fallback with captive portal + local DNS (opens landing page)
  • LAN discovery (mDNS/LLMNR + DHCP reservation hints)
  • Optional tethering (USB↔Ethernet) and LAN↔Wi-Fi bridge mode
  • USB to LAN compatibility?
• Captive portal: intercept + redirect to landing; HTTPS-blocking bypass note.
• Device discovery: mDNS inswitch.local (and variant) with proper firewall settings
• Config store
  • Location + format (e.g., /etc/inswitch/config.yaml + /data/…)
  • Transactional write with rollback on network loss
• Tailscale
  • Preinstalled client; first-run auth flow (QR + URL shown in portal)
  • Status JSON for UI; persistent state; ACL docs
• Security
  • Firewall defaults (allow LAN portal/API; block WAN where needed)
• Updates UI (maybe through landing page instead?)
  • Read versions and display in landing page for OS/app/docker/forklift
  • Trigger app/container updates; progress + logs via landing page?
  • Firmware updater hook (OS hook?)

...there is probably a lot missing ;)

Acceptance criteria

@Mikrodoktor please add your expectation here :)

• From factory reset, user reaches landing page via either LAN or Wi-Fi in ≤2 min.
• Wizard connects the device to a protected Wi-Fi and keeps access (no lock-out).
• AP fallback works if STA fails; portal opens automatically.
• Tailscale shows “connected” after auth; status visible in UI.
• Config changes are atomic; rollback works on failure.
• Updates show progress and final status; device remains reachable.
• Support bundle downloadable from UI.
• Can connect to nearby Wifi
• Need to be able to update the device in offline-only mode somehow

[ethanjli]

I've only read through the first half of the issue (and skimmed through the second half) so far, but my first question (perhaps for @Mikrodoktor ) is: would it be acceptable for users if the first-time setup process required users to follow the Wi-Fi Path (i.e. connect the client device to the machine's Raspberry Pop's Wi-Fi hotspot) for the first-time connection? If we can avoid the LAN path (i.e. connect both the client device and the Raspberry Pi to a network router) for the onboarding experience, it could simplify the process and our quickstart guide; and the Wi-Fi path where we have the most control over the network configuration (so there are fewer ways the quickstart process could be blocked by factors outside our control).

[beniroquai]

Could we alternatively (to the Router option) "simply" ship an USB-to-LAN connector?

[ethanjli]

These are some random points that we should discuss! Please complain/change anything :)

For many of the things here, I'll need a bit more context/discussion to understand them. In the meantime, I wonder if it might help to organize this overall "onboarding" project into some smaller subprojects, to make the onboarding process less overwhelming (for me, and for users). I sketched out one concept for how we can decompose the onboarding process into a set of smaller guides; maybe only guides 1, 2, and 3 (and maybe also 4) are really necessary for the first run; and then the user can visit the subsequent guides later—maybe on the second boot—if those aren't things the user strongly needs for their use-case:

This might also help us to prioritize which things are most urgent for us to improve/implement, vs. which things can wait a month or two.

Could we alternatively (to the Router option) "simply" ship an USB-to-LAN connector?

I think that would be a good idea...but whether or not we ship a USB-to-Ethernet adapter, we should still support users in getting their RPi's connected to the internet, so that any device can have internet access when it's connected to the RPi. Here are some possible options, which are not mutually exclusive; we'd have to decide which ones we want to promote/support more, based on associated tradeoffs:

1. Ship a USB Wi-Fi dongle in the RPi. Then users can connect their client device to the RPi's Wi-Fi hotspot (which will be served from the Wi-Fi dongle), and then configure the RPi to connect to a router's Wi-Fi network (which will use the RPi's internal Wi-Fi module) to give the RPi internet access.
2. Ship a USB-to-Ethernet adapter, and maybe also an Ethernet cable. Then users can connect their client device to the RPi via a direct Ethernet connection, and then configure the RPi to connect to the router's Wi-Fi network (which will use the RPi's internal Wi-Fi module) to give the RPi internet access.
3. Ship an Ethernet cable. Then users can plug the RPi into a router (or an Ethernet port in the wall) to give the RPi internet access. And users can connect their client device to the RPi's Wi-FI hotspot (which will be served from the RPi's internal Wi-Fi module).

The nice thing about Ethernet cables is that they are reliable as a fallback option for accessing the RPi if something goes wrong with Wi-Fi (which is possible because Wi-Fi is so complex), so that users don't have to open up the machine to extract the SD card and re-flash it with a clean version of the OS if they mess up their Wi-Fi settings to the point that they can no longer access the RPi via Wi-Fi.

[Mikrodoktor]

Okay I am the user! Not Armin :-). Hope this helps.

"I don't care about details. I want to know at least one foolproof (better 2) and for me easily accessible way to get the microscope running. I do not care how. I want you = UC2 to guide me through the process and deliver any hardware or software features with my FRAME, if I don't have them!

• I want to be informed before buying what I need to operate the FRAME successfully and if I do not have it I want the option to it get from UC2 with my delivery.
• I receive the FRAME shipment.
• I get a link to the up-to-date operational manual on UC2 Github or elsewhere.
• I unbox and install.
• I plug everything together.
• I power everything on.
• I download and install software from UC2 Github or website according to operation manual if required.
• I follow the instructions to get the microscope operating.
• I want to conduct a number of test scenarios which demonstrate to me, that all basic functions work properly.
  E.g. running test protocolls ...

[Mikrodoktor]

My suggestion: let us decide on ONE foolproof way of how to install and setup the microscope and get it running and 3-5 test scenarios which show that the most important basic functions are running properly.
If we have this, we update the operational manual and then decide, what is next.

My ideas for test scenario

• Taking images with a number of relevant setting and store them (different objectives, different ligh settings ...) .
• Running a loop of moving the microscope to a predefined position (e.g. from home position), taking pictures and checking repeatibility ...

[beniroquai]

Thanks Armin / User for this feedback! Sounds great to me
@ethanjli I love the flowchart! If we could implement this, it would be really really cool.
Re: networking (@Mikrodoktor ) => ONE way would be either Wifi or LAN? My suggestion would be to again look into what Opentrons did. They actually have both. A desktop app (which you have to install) is basically a portscanner + update manager that manages updates for the RPI by downloadingthem to a computer and uploading them to the rpi. This seems to be the best of all worlds to me at the moment. A captive portal through the desktop app can connect the opentrons to a local internetable network so that you can e.g. install packages on the opentrons. What do you think? We can test it with our opentrons if you like.

The test procedures sound like a next step after onboarding (rather low-level at the moment => networking, configs, etc.).

[beniroquai]

I'm all up for ethernet adapters. Could we take any? Should we rather take USB-C adapters these days?

[ethanjli]

They actually have both. A desktop app (which you have to install) is basically a portscanner + update manager that manages updates for the RPI by downloadingthem to a computer and uploading them to the rpi.

I think this could be a worthwhile goal to work towards over the next several months, but it adds certain complexities (e.g. related to desktop app signing for macOS & Windows app security stuff, or platform compatibility things, or packaging Linux apps in a way that would work for any distro the customer might want to use, or a number of technical factors which are outside our control and thus harder to troubleshoot) which I'd prefer to avoid in our first or second iteration at simplifying the onboarding process. Let's start with something less ambitious which is imperfect but which would be easy for us 1) to communicate to users and 2) to help users troubleshoot, and then as we do more iterations at improving the onboarding process in the coming months, we can work towards something more sophisticated which might be more approachable for customers who have less experience troubleshooting technology. I'm sure that as we get feedback from our initial customers in the coming months, they'll give us valuable feedback/input which will shape the fundamental design of any desktop app we build, before we have to spend time building that app (which would be time not spent building other things) :)

Should we rather take USB-C adapters these days?

Maybe you could provide an Ethernet-to-USB-C adapter, and also (optionally?) provide a USB-A-to-USB-C adapter which probably only costs a few euros

[ethanjli]

For the record, @Mikrodoktor and I had a meeting today to follow up on the discussion here. I took notes for myself about what we discussed: https://www.notion.so/2025-09-26-Armin-Ethan-Discussion-22d4e612c78a8022831dc141ed8771e1?source=copy_link

[beniroquai]

Thanks! One option would be to use other infrastructure? If Johannes has done his job on paying apple deverloper fees, we could join his orkestrator to do it from there? We will be connected to this in the longterm run anyway (lab automation stuff). But true, long term!

RE: USB-lan -> I think U-Green is great. @ranranking maybe I could order one locally and we test it? https://de.ugreen.com/products/ugreen-usb-c-ethernet-adapter-gigabit-lan-adapter-netzwerkadapter-kompatibel-mit-macbook-air-pro-ipad-pro-air-surface-pro-8-7-galaxy-tabs-steam-deck-spielkonsole-switch-und-mehr-typ-c-geraten?variant=44505125323064&country=DE&currency=EUR&utm_medium=product_sync&utm_source=google&utm_content=sag_organic&utm_campaign=sag_organic&gad_source=1&gad_campaignid=22128940306&gbraid=0AAAAApUGCxF7vx6GtuxSwNiJIEsr9HpL5&gclid=CjwKCAjw89jGBhB0EiwA2o1On-O0gFlT2bnzwWvuGxEHN81oAbHh-vmR2v_R6nMzpkrVCW3iQaHTAxoCxjMQAvD_BwE

[ranranking]

Yes, sure, looks good, I think Alex also ordered before LAN adapter like that.

Maybe on Amazon? Christine wants also some two USB charger, I can order them together