Skip to content

Commit 86d1bd6

Browse files
Copilotbeniroquai
Copilot
and
beniroquai
committed
Address TODO items: improve links, WiFi setup, and µManager documentation
Co-authored-by: beniroquai <4345528+beniroquai@users.noreply.github.com>
1 parent ce1a669 commit 86d1bd6

2 files changed

Lines changed: 137 additions & 50 deletions

File tree

‎docs/05_ImSwitch/01_Quickstart.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ There are two ways to set up the Raspberry Pi for ImSwitch:
8282
### **Option 1: Manual Installation**
8383

8484
:::warning
85-
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)
85+
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. See [**Option 2: Using the Pre-Built Forklift Image**](#option-2-using-the-pre-built-forklift-image).
8686
:::
8787

8888
#### **Step 1: Install Raspberry Pi OS**
@@ -423,9 +423,29 @@ If you haven't provided the token, you can simply follow the link and add this t
423423

424424
#### Connect to Wifi
425425

426-
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.
426+
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, you can do that by following the steps below.
427427

428-
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.
428+
##### Connection Options:
429+
430+
**Option A: Connect to your home WiFi network**
431+
1. SSH into the Raspberry Pi: `ssh UC2@192.168.4.1` (password: `youseetoo`)
432+
2. Use NetworkManager CLI to connect:
433+
```bash
434+
sudo nmcli dev wifi connect "YOUR_WIFI_NAME" password "YOUR_WIFI_PASSWORD" ifname wlan0
435+
```
436+
3. Verify connection: `ip a show wlan0` - you should see an inet address
437+
438+
**Option B: Use your cellphone's hotspot**
439+
1. Enable hotspot on your phone with a simple name (avoid special characters)
440+
2. Connect the Raspberry Pi following Option A steps above
441+
3. This is useful for initial setup when you don't have access to a local network
442+
443+
**Recovery: If you get locked out**
444+
- Use a LAN/Ethernet adapter connected to your router
445+
- Access the Pi via LAN on `192.168.5.1` using SSH
446+
- Then reconfigure WiFi using the methods above
447+
448+
If you have an existing WiFi network you want to connect to, follow the troubleshooting steps below if the connection fails.
429449

430450
**Problem (one‑sentence)**
431451
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*.

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

Lines changed: 114 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -2,75 +2,142 @@
22

33
ImSwitch now includes an official device adapter for µManager, enabling seamless integration between ImSwitch hardware control and µManager's powerful acquisition and analysis capabilities.
44

5-
TODO: Improve the text and explain a bit how we can use the device in micromanager
5+
## Using ImSwitch with µManager
6+
7+
The ImSwitch device adapter allows you to control UC2 hardware directly from µManager, combining the best of both worlds: ImSwitch's UC2 hardware control with µManager's powerful acquisition and analysis tools.
8+
9+
### What You Can Control
10+
11+
- **Lasers**: Up to 4 laser devices with individual power control
12+
- **Motorized Stages**: XY and Z positioning with precise movement control
13+
- **Camera**: Integrated camera control (requires separate camera driver installation)
14+
- **Synchronized Operations**: Coordinate all devices for complex acquisition protocols
15+
16+
### Key Benefits
17+
18+
- **Familiar Interface**: Use µManager's standard controls for UC2 hardware
19+
- **Advanced Acquisition**: Leverage µManager's multi-dimensional acquisition capabilities
20+
- **Scripting Support**: Automate workflows using µManager's macro and scripting features
21+
- **Community Plugins**: Access to µManager's extensive plugin ecosystem
622

723
:::warning
8-
This is a work in progress
24+
This integration is actively being developed and refined
925
:::
1026

11-
Basic idea: The developments from are now part of the micromanager core and device so that one can integrate the DLL into their devices. Tthen one can use the stage and the lasers in combination with micromanager
27+
## Background
1228

13-
Source: https://github.com/openUC2/openUc2MicroManagerDeviceAdapter/edit/master/Readme.md
14-
and the dll: https://github.com/openUC2/mmCoreAndDevices
29+
The UC2 device adapter has been integrated into the µManager core, allowing users to control UC2 hardware (stages, lasers, and other devices) directly through µManager's interface. This integration enables sophisticated microscopy workflows while maintaining the flexibility of the UC2 ecosystem.
1530

16-
## Developped by Christian Karras, April 2025
17-
# Version: 1.0.0
18-
# Jena, 14.05.2025
31+
**Developer**: Christian Karras
32+
**Version**: 1.0.0
33+
**Development Location**: Jena
34+
**Date**: May 2025
1935

20-
# Scope of use / Development Environment:
21-
Micromanager Version: 2.0.3 20250304
22-
MM Core Version: 11.4.1
23-
Device API Verions: 71
24-
Module API Verison: 10
25-
Windows version: 11 Home 23H2 Build 22631.5039
36+
**Sources**:
37+
- [OpenUC2 µManager Device Adapter](https://github.com/openUC2/openUc2MicroManagerDeviceAdapter)
38+
- [µManager Core Integration](https://github.com/openUC2/mmCoreAndDevices)
2639

27-
openUC2 Verion: UC2_Feather V2.0 Mar 9 202520:25:00
28-
Camera Version: Daheng Mercury 2 1220 vs. MV-CE060-10UC
29-
30-
The developped Micro Manager Device Adapter comprises the up to 4 lasers as well as an XY and a Z Stage.
40+
## System Requirements
3141

32-
The camera is not includeded! Instead the camera should be separately installed during hardware configuraration process
42+
- **µManager Version**: 2.0.3 (20250304) or newer
43+
- **µManager Core Version**: 11.4.1 or newer
44+
- **Device API Version**: 71 or newer
45+
- **Module API Version**: 10 or newer
46+
- **Operating System**: Windows 11, macOS, or Linux
47+
- **UC2 Hardware**: UC2_Feather V2.0 or newer
48+
- **Supported Cameras**: Daheng Mercury 2 1220, MV-CE060-10UC, or similar
49+
## Device Capabilities
3350

34-
# Setting up UC2 in Micromanager
35-
1.) Open Micromanager and start with "None" configuration file
36-
2.) Goto Devices -> Hardware configuration wizard
37-
- Create New configuration, Next
38-
- From available devices choose openUC2/openUC2Hub device and Add
39-
- Set proper COM Port
40-
- Set BaudRate to 115200 (NOTE: A falsely set Baudrate will most likely lead to a crash of MM),
41-
- Select all devices in the list
42-
- Choose correct Camera (Tested with Daheng Mercury 2 1220 vs. MV-CE060-10UC, include by adding Daheng Device)
43-
- Finish HW configuration wizard by clicking through windows upon device choice and save the config file.
51+
The µManager Device Adapter supports:
52+
- **Up to 4 laser controllers** with individual power control
53+
- **XY and Z motorized stages** with precise positioning
54+
- **Hardware synchronization** for coordinated operations
4455

45-
# Using Lasers
46-
- Choose laser in shutter dropdown menue
47-
- Open / Close shutter will switch the laser on and off (note: "Auto" should be deactivated)
48-
- Set laser power for different lasers via "Devices" -> "Device Property Browser" -> "openUC2-Laser1-UC2LaserPower", "openUC2-Laser2-UC2LaserPower","openUC2-Laser3-UC2LaserPower","openUC2-Laser4-UC2LaserPower"
56+
:::info
57+
The camera must be configured separately during the hardware configuration process. The UC2 adapter handles only the motorized components and lasers.
58+
:::
4959

50-
# Using Stages
51-
- Stages are used via common MM controlls
60+
## Setting up UC2 in µManager
5261

53-
# Setting Basic Device variables
54-
- For Version maintaining change ALL relevant device variables in "UC2DEFAULTS.h" bevor rebuilding
55-
- This counts especially for
56-
- IDs of Lasers and XYZ Stages
57-
- Default init values of the properies (Homing setting and speed for the axes)
58-
- Firmware check string: Currently, only the State Identificator Name is checked and must be "UC2_Feather" for correct firmware detection
59-
- Thresholds of the XYZ Stages. Currently no endswitch is installed and no endswitch controll is implemented
62+
### Initial Configuration
6063

61-
# Further remarks
62-
- IsContinuousFocusDrive is set to False
63-
- IsXYStageSequenceable is set to False
64+
1. **Open µManager** and start with "None" configuration file
65+
2. **Access Hardware Configuration Wizard**:
66+
- Go to **Devices** → **Hardware Configuration Wizard**
67+
- Create new configuration, click **Next**
68+
- From available devices choose **openUC2/openUC2Hub** device and **Add**
6469

70+
### Device Configuration
6571

72+
3. **Configure Communication**:
73+
- Set the proper **COM Port** (check Device Manager on Windows)
74+
- Set **BaudRate** to **115200**
75+
76+
:::warning
77+
An incorrect BaudRate setting will likely cause µManager to crash
78+
:::
79+
80+
4. **Select Devices**:
81+
- Select all UC2 devices in the list (lasers, stages)
82+
- Add your camera separately (tested with Daheng Mercury 2 1220, MV-CE060-10UC)
83+
- Complete the Hardware Configuration Wizard and **save the config file**
84+
85+
## Using Laser Control
86+
87+
### Laser Operation
88+
- **Select laser**: Choose the desired laser from the shutter dropdown menu
89+
- **Laser control**: Open/Close shutter switches the laser on and off
90+
- **Power settings**: Set laser power via **Devices** → **Device Property Browser**:
91+
- `openUC2-Laser1-UC2LaserPower`
92+
- `openUC2-Laser2-UC2LaserPower`
93+
- `openUC2-Laser3-UC2LaserPower`
94+
- `openUC2-Laser4-UC2LaserPower`
95+
96+
:::tip
97+
Disable "Auto" shutter mode for manual laser control
98+
:::
6699

67-
## Overview
100+
## Stage Control
101+
### Stage Operation
102+
- **XY and Z stages** are controlled using µManager's standard stage controls
103+
- **Movement**: Use the stage control panel or coordinate input fields
104+
- **Precision**: Supports precise positioning for multi-point acquisitions
105+
106+
## Advanced Configuration
107+
108+
### Device Variables (for Developers)
109+
110+
When building custom configurations, modify the following variables in `UC2DEFAULTS.h`:
111+
112+
**Critical Settings**:
113+
- **Device IDs**: Laser and XYZ stage identifiers
114+
- **Initialization values**: Homing settings and axis speeds
115+
- **Firmware detection**: State identifier name must be "UC2_Feather"
116+
- **Stage thresholds**: Currently no endstop switches are implemented
117+
118+
### Current Limitations
119+
120+
- **Continuous Focus**: `IsContinuousFocusDrive` is set to False
121+
- **Stage Sequencing**: `IsXYStageSequenceable` is set to False
122+
- **Endstops**: No endstop switch control is currently implemented
123+
124+
## Integration Benefits
68125

69126
The ImSwitch µManager device adapter provides:
70127
- **Hardware Control**: Full access to ImSwitch-controlled devices from µManager
71-
- **Synchronized Acquisition**: Coordinated control of multiple devices
128+
- **Synchronized Acquisition**: Coordinated control of multiple devices
72129
- **Standard Interface**: Uses µManager's standard device API
73130
- **Cross-Platform**: Available on Windows, macOS, and Linux
74131
- **Official Support**: Integrated into µManager nightly builds
75132

133+
## Next Steps
134+
135+
After configuration, you can:
136+
- **Run acquisitions** using µManager's Multi-Dimensional Acquisition tool
137+
- **Create automated workflows** with µManager's scripting capabilities
138+
- **Use advanced plugins** for specialized imaging techniques
139+
- **Export data** in standard formats for analysis
140+
141+
For more advanced usage examples, see the [µManager documentation](https://micro-manager.org/).
142+
76143

0 commit comments

Comments
 (0)