Skip to main content

ImSwitch OS

The ImSwitch OS is a complete, pre-configured operating system image designed specifically for UC2 microscopy systems. It provides a ready-to-use environment with all software, drivers, and configurations pre-installed.

Images and Screenshots​

(the screenshots are outdated, so they've been deleted)

Overview​

The ImSwitch OS is a specialized Raspberry Pi OS image that includes:

  • ImSwitch with all dependencies pre-installed
  • UC2-REST Python interface for ESP32 communication
  • UC2-ESP32 firmware flashing tools
  • Docker with pre-built ImSwitch containers
  • Camera drivers for supported hardware
  • Configuration templates for common setups
  • Web interface for remote control

Features​

Pre-Installed Software​

  • ImSwitch Core: Latest stable version with all modules
  • Docker Environment: Pre-built containers ready to run
  • UC2-REST Library: Python interface for hardware control
  • Firmware Tools: ESP32 flashing utilities and firmware
  • Development Tools: Python, Git, VS Code Server (optional)

Hardware Support​

  • Cameras: HIK, Daheng, Raspberry Pi, USB cameras
  • Motors: UC2-ESP32 controlled stages and focus systems
  • Illumination: LED arrays, lasers, matrix displays
  • Sensors: Environmental monitoring, feedback systems

Network Features​

  • WiFi Hotspot: Create isolated network for microscope control
  • Web Interface: Browser-based control panel (Cockpit)
  • SSH Access: Remote terminal access
  • VNC Server: Remote desktop access

Installation​

Requirements​

  • Raspberry Pi 4 (4GB RAM minimum, 8GB recommended)
  • MicroSD Card (32GB minimum, Class 10 or better)
  • UC2 Hardware (optional for initial setup)

Step 1: Download Image​

# Download the latest ImSwitch OS image or go to Zenodo and download it here https://zenodo.org/records/14988987
wget https://zenodo.org/records/14988987/files/rpi-uc2-27f9a21.zip?download=1

Step 2: Flash to SD Card​

Using Raspberry Pi Imager (Recommended):

  1. Download Raspberry Pi Imager
  2. Select "Use custom image" and choose the downloaded .img.xz file
  3. Select your SD card
  4. Click "Write" and wait for completion

Using dd (Linux/macOS):

# Extract image
xz -d imswitch-forklift-os.img.xz

# Flash to SD card (replace /dev/sdX with your SD card device)
sudo dd if=imswitch-forklift-os.img of=/dev/sdX bs=4M status=progress
sync

Step 3: First Boot​

  1. Insert SD card into Raspberry Pi
  2. Power on the Raspberry Pi
  3. Observe for an SSID with name openuc2-XXX-XXX-XXX

Configuration​

For detailed information about ImSwitch configuration files, see the Configuration Guide.

Quick Start Configuration:

# Navigate to configuration directory
cd /home/pi/ImSwitchConfig

Copy a template configuration. Configuration files are stored in /home/pi/Documents/ImSwitchConfig/config/ and can be edited using the desktop interface or via SSH.

# Edit configuration for your hardware
nano config/imcontrol_options.json #=> enter the name you want to use

Advanced Features​

Custom Configurations​

Hardware Configuration:

# Edit hardware configuration
nano /home/pi/ImSwitchConfig/imcontrol_setups/my_setup.json

# Set as active configuration
echo '{"setupFileName": "my_setup.json"}' > /home/pi/ImSwitchConfig/config/imcontrol_options.json

Scripting:

# Custom scripts directory
ls /home/pi/ImSwitchConfig/scripts/

# Add your custom scripts
cp my_script.py /home/pi/ImSwitchConfig/scripts/

Troubleshooting​

Common Issues​

Hardware not detected:

# Check USB devices
lsusb

# Check serial ports
ls /dev/tty*

Log Files​

Important log locations:

  • ImSwitch: /home/pi/.imswitch/logs/
  • System: /var/log/syslog
  • Docker: journalctl -u imswitch-docker

Recovery​

Reset to defaults:

# Reset ImSwitch configuration
rm -rf /home/pi/ImSwitchConfig/config/*
# then restart imswitch

Support and Resources​

Getting Help​

Next Steps​

After setting up ImSwitch OS:

  1. Configure your hardware - Set up specific devices
  2. Basic usage tutorial - Learn ImSwitch operation
  3. Advanced tutorials - Explore advanced features