final remakrs and iprovements

Author: beniroquai

docs/05_ImSwitch/01_Quickstart.md

@@ -3,8 +3,9 @@
 The Raspberry Pi serves as a bridge between the UC2-ESP board and a USB3 camera, running the ImSwitch software inside a Docker container. The system allows you to control the microscope through a web interface accessible from a phone or laptop.
 
 > **Note:** This setup is experimental! You can try a demo version of the latest ImSwitch here:
-> - [Live Demo](https://imswitch.openuc2.com/imswitch/index.html)
-> - [ImSwitch API](https://imswitch.openuc2.com/docs)
+> - [Live Demo](https://imswitch.openuc2.com/imswitch/index.html) (currently not active)
+> - [React Demo](https://youseetoo.github.io/imswitch) 
+> - [ImSwitch API](https://youseetoo.github.io/api/api.html) (may be outdated)
 
 ---
 
@@ -23,20 +24,20 @@ The system runs Raspberry Pi OS Lite and includes a Docker integration for ImSwi
 - **Password:** `youseetoo`
 
 To configure the hotspot using RaspAP:
-1. Open a browser and go to [http://10.3.141.1/](http://10.3.141.1/)
+1. Open a browser and go to [http://192.168.4.1/](http://192.168.4.1/)
 2. Login with:
    - **Username:** `admin`
    - **Password:** `secret`
 
 ### Accessing ImSwitch
 If the Docker container starts automatically, access ImSwitch at:
-- [https://10.3.141.1:8001/imswitch/index.html](https://10.3.141.1:8001/imswitch/index.html)
+- [https://192.168.4.1:8001/imswitch/index.html](https://192.168.4.1:8001/imswitch/index.html)
 - Ignore self-signed certificate warnings (this will be fixed later).
 
 ### Connecting via SSH
 To manually start ImSwitch:
 ```sh
-ssh uc2@10.3.141.1  # Password: youseetoo
+ssh pi@192.168.4.1  # Password: youseetoo
 cd ~/Desktop
 ./launch_docker_container.sh
 ```
@@ -66,7 +67,7 @@ More details: [ImSwitchConfig GitHub](https://github.com/openUC2/imswitchconfig)
 - Connect **USB3 Camera** to Raspberry Pi
 
 To access ImSwitch via a browser:
-- Open: [https://10.3.141.1:8001/imswitch/index.html](https://10.3.141.1:8001/imswitch/index.html)
+- Open: [https://192.168.4.1:8001/imswitch/index.html](https://192.168.4.1:8001/imswitch/index.html)
 
 ![](./IMAGES/imswitchraspi/ImSwitchInTheWeb.png)
 
@@ -80,6 +81,10 @@ There are two ways to set up the Raspberry Pi for ImSwitch:
 
 ### **Option 1: Manual Installation**
 
+:::warning
+We provide the easier installation with the prebuild OS image from the forklifted ImSwitch-OS; Please scroll down to use this if you want to have a real quick start (TODO: Add link to Option2)
+:::
+
 #### **Step 1: Install Raspberry Pi OS**
 1. Download and install the Raspberry Pi Imager: [Download Here](https://www.raspberrypi.com/software/)
 
@@ -158,7 +163,7 @@ The image is built from the following workflow:
 
 #### **Requirements**
 - microSD Card with >32GB
-- Raspberry Pi 4 or preferably Pi 5 (8GB RAM recommended)
+- Raspberry Pi 4 (*not recommended anymore as we need more RAM*) or preferably Pi 5 (8GB RAM recommended)
 - microSD Card reader
 
 If you prefer a faster setup, you can use this **pre-built image** that includes all necessary software and drivers. This image was created with the [Forklift Project](https://github.com/forklift-run) and automates all setup steps.
@@ -179,25 +184,33 @@ Use the Raspberry Pi Imager to flash the image onto an SD card, then insert the
 4. Do **not** specify additional user-specific settings.
 
 ##### **Default Credentials**
-- **SSID:** `openUC2-unknown`
-- **WiFi Password:** `copepode`
+- **SSID:** `openUC2-XXXX` (`XXX` corresponds to a random number bsed on the MAC address)
+- **WiFi Password:** `copepode` (now: `youseetoo`)
 - **Username:** `pi`
 - **User Password:** `youseetoo`
 
 > **Note:** The Forklift image is updated automatically and ensures all software is correctly configured.
 
 :::warning
-If you want to have Internet on the Raspberry Pi, you can either plug the LAN port into a router with internet - then the wifi that is shared by the access point is automatically briding that connection. Alternatively, you can use an Android phone in USB access point mode and share the internet connection by that mean.
+**INTERNET ACCESS:** If you want to have Internet on the Raspberry Pi, you can either plug the LAN port into a router with internet - then the wifi that is shared by the access point is automatically briding that connection. Alternatively, you can use an Android phone in USB access point mode and share the internet connection by that mean.
 :::
 
-:::error
-In case the GUI hangs - this might be due to an older version that expected internet to load javascript libraries/fonts. It times out after 60s and renders the ImSwitch webapp - please update the software.
+:::warning
+**GUI HANGS:** In case the GUI hangs - this might be due to an older version that expected internet to load javascript libraries/fonts. It times out after 60s and renders the ImSwitch webapp - please update the software.
 :::
 
-
 For a detailed breakdown of the image creation process, see:
 [ImSwitch OS GitHub Setup Script](https://github.com/beniroquai/imswitch-os/blob/main/setup.sh#L60)
 
+#### **Updating Forklift configuration**
+
+This will pull the latest pallet and forklift configuration. Be aware, that system rleated conifgurations may be overwritte. The command is the following:
+
+```
+forklift pallet upgrade --force @main
+```
+
+
 #### **Connecting to the Raspberry Pi**
 1. Wait until the Raspberry Pi boots and you see the SSID `openUC2-unknown`.
 2. Connect to the SSID and navigate to `http://192.168.4.1:9090` to access Cockpit.
@@ -399,15 +412,27 @@ If you are facing a problem with a wrong docker configuration (i.e. Docker Compo
 
 The filename of the file containing the tailscale auth token should be tailscale-auth-key. The file will need to exist on the boot partition in a new run subdirectory of the init-root directory.
 
+You can start tailscale by entering the following in the command:
+
+```
+sudo tailscale up # down for stopping
+```
+
+If you haven't provided the token, you can simply follow the link and add this to your local tailscale network. 
+
+
 #### Connect to Wifi
 
+TODO: This needs a revision to make sure we have a direct way of connecting to a local network. Explain how we can use the cellphone's hotspot to get starting. Also: in case we lock ourselves out: We can use a LAN adapter and connect that to our network to access the pi via LAN on 192.168.5.1. 
 
 By default, the forklift configuration provides an access point and maps internet from the LAN to the AP conveniently. If you have an existing access point and you want to connect to that one using the raspberry pi can you can do that by following the follwoing steps.
 
 **Problem (one‑sentence)**
 Saved profile contains a malformed `ssid=` (often a trailing space added by *nmtui*). NetworkManager then scans for a name that does not exist and returns *WLAN konnte nicht gefunden werden*.
 
 
+
+
 ##### Quick‑fix workflow
 
 | Goal                                       | Command / action                                                                                                                                                                                                              |
@@ -421,6 +446,8 @@ Saved profile contains a malformed `ssid=` (often a trailing space added by *nmt
 
 ##### Using *nmtui* instead of CLI
 
+
+
 1. `sudo nmtui` → *Activate a connection* → highlight your network → **Add** (or **Edit**)
 2. Enter **SSID** exactly (`openUC2`), security = *WPA & WPA2 Personal*, fill password.
 3. Leave *BSSID* blank.

docs/05_ImSwitch/Advanced/01_Installation/Native.md

@@ -1,4 +1,4 @@
-# ImSwitch Native Python Installation
+# ImSwitch Native Python Installation (With QT GUI)
 
 This guide covers installing ImSwitch directly on your system using Python, suitable for development and advanced users who need full control over the installation.
 
@@ -154,6 +154,44 @@ For advanced users who want full control over the installation process, here are
 - Qt5/Qt6 development libraries
 - OpenGL support
 
+
+In all cases, you can start the GUI (in case all the dependencies are properly installed) using the `is_headless=0` flag. For this create a python file (e.g. `main2.py`) and launch this:
+
+```py
+if __name__ == '__main__':
+    from imswitch.__main__ import main
+    '''
+    To start imswitch in headless with a remote config file, you can add additional arguments:
+    main(is_headless=True, default_config="/Users/bene/ImSwitchConfig/imcontrol_setups/example_virtual_microscope.json", http_port=8001, ssl=True, data_folder="/Users/bene/Downloads")
+    - is_headless: True or False
+    - default_config: path to the config file
+    - http_port: port number^ 
+    - ssl: True or False
+    - data_folder: path to the data folder => in docker this could be e.g. Volumes, media in combination with external scanning or any other volume that is direclty mapped as a folder to Imswitch
+    - scan_ext_data_folder: True or False => we will look for any externally connected devices (usb) that is mounted under /Volumes or /media
+    example:
+    main(is_headless=True, data_folder="/Users/bene/Downloads")
+    
+    # kill -9 $(lsof -ti:8001)
+    '''
+    #main(is_headless=False) ## this has to be maintained for DOCKER!
+    #main(default_config="/Users/bene/ImSwitchConfig/imcontrol_setups/FRAME.json", is_headless=True, http_port=8001) ## this has to be maintained for DOCKER!
+    #main(default_config="/Users/bene/ImSwitchConfig/imcontrol_setups/example_uc2_lightsheet_hik.json", is_headless=True, http_port=8001) ## this has to be maintained for DOCKER!
+    main(default_config="/Users/bene/ImSwitchConfig/imcontrol_setups/example_virtual_microscope.json", is_headless=False, http_port=8001, socket_port=8002, scan_ext_data_folder=True, data_folder="~/Downloads", ext_drive_mount="/Volumes") 
+```
+
+With this we will see the qt app load:
+
+![](../IMAGES/gui/qt_load.png)
+
+Below you will find ways how to install the dependencies. In a nutshell: You install imswitch with the `PyQt5` flag which will install napari and its dependencies (e.g. `pip install .[PyQt5]` assuming you are in the same folder as the cloned ImSwitch (openUC2 version) repo). The ImSwitch app in QT looks as follows: 
+
+![](../IMAGES/gui/qt_imswitch.png)
+
+:::warning
+**Discontinued support for QT**: We have stopped supporting the qt framework as we push towards the headless mode - please expect errors and unsupported functions!
+:::
+
 #### Ubuntu/Debian (GUI)
 
 ```bash
@@ -195,7 +233,7 @@ imswitch-env\Scripts\activate
 # Clone and install
 git clone https://github.com/openUC2/imSwitch 
 cd imSwitch
-pip install -e .
+pip install -e .[PyQt5]
 
 # Install UC2-REST
 git clone https://github.com/openUC2/UC2-REST
@@ -220,7 +258,7 @@ source ~/imswitch-env/bin/activate
 # Install ImSwitch
 git clone https://github.com/openUC2/imSwitch ~/ImSwitch
 cd ~/ImSwitch
-pip install -e .
+pip install -e .[PyQt5]
 
 # Install UC2-REST
 git clone https://github.com/openUC2/UC2-REST ~/UC2-REST

docs/05_ImSwitch/Advanced/02_Usage/Micromanager.md

@@ -2,6 +2,8 @@
 
 ImSwitch now includes an official device adapter for µManager, enabling seamless integration between ImSwitch hardware control and µManager's powerful acquisition and analysis capabilities.
 
+TODO: Improve the text and explain a bit how we can use the device in micromanager 
+
 :::warning
 This is a work in progress
 :::