feat: Add multi-camera support with LiveController camera switching

firmware/controller/src/commands/commands.cpp

@@ -26,6 +26,13 @@ void init_callbacks()
     cmd_map[TURN_OFF_ILLUMINATION] = &callback_turn_off_illumination;
     cmd_map[SET_ILLUMINATION] = &callback_set_illumination;
     cmd_map[SET_ILLUMINATION_LED_MATRIX] = &callback_set_illumination_led_matrix;
+    // Multi-port illumination commands (firmware v1.0+)
+    cmd_map[SET_PORT_INTENSITY] = &callback_set_port_intensity;
+    cmd_map[TURN_ON_PORT] = &callback_turn_on_port;
+    cmd_map[TURN_OFF_PORT] = &callback_turn_off_port;
+    cmd_map[SET_PORT_ILLUMINATION] = &callback_set_port_illumination;
+    cmd_map[SET_MULTI_PORT_MASK] = &callback_set_multi_port_mask;
+    cmd_map[TURN_OFF_ALL_PORTS] = &callback_turn_off_all_ports;
     cmd_map[ACK_JOYSTICK_BUTTON_PRESSED] = &callback_ack_joystick_button_pressed;
     cmd_map[ANALOG_WRITE_ONBOARD_DAC] = &callback_analog_write_onboard_dac;
     cmd_map[SET_DAC80508_REFDIV_GAIN] = &callback_set_dac80508_defdiv_gain;

firmware/controller/src/commands/light_commands.cpp

@@ -29,3 +29,70 @@ void callback_set_illumination_intensity_factor()
     if (factor > 100) factor = 100;
     illumination_intensity_factor = float(factor) / 100;
 }
+
+/***************************************************************************************************/
+/*************************** Multi-port illumination commands (v1.0+) ******************************/
+/***************************************************************************************************/
+
+// Command byte layout: [cmd_id, 34, port, intensity_hi, intensity_lo, 0, 0, crc]
+void callback_set_port_intensity()
+{
+    int port_index = buffer_rx[2];
+    uint16_t intensity = (uint16_t(buffer_rx[3]) << 8) | uint16_t(buffer_rx[4]);
+    set_port_intensity(port_index, intensity);
+}
+
+// Command byte layout: [cmd_id, 35, port, 0, 0, 0, 0, crc]
+void callback_turn_on_port()
+{
+    int port_index = buffer_rx[2];
+    turn_on_port(port_index);
+}
+
+// Command byte layout: [cmd_id, 36, port, 0, 0, 0, 0, crc]
+void callback_turn_off_port()
+{
+    int port_index = buffer_rx[2];
+    turn_off_port(port_index);
+}
+
+// Command byte layout: [cmd_id, 37, port, intensity_hi, intensity_lo, on_flag, 0, crc]
+void callback_set_port_illumination()
+{
+    int port_index = buffer_rx[2];
+    uint16_t intensity = (uint16_t(buffer_rx[3]) << 8) | uint16_t(buffer_rx[4]);
+    bool turn_on = buffer_rx[5] != 0;
+
+    set_port_intensity(port_index, intensity);
+    if (turn_on)
+        turn_on_port(port_index);
+    else
+        turn_off_port(port_index);
+}
+
+// Command byte layout: [cmd_id, 38, mask_hi, mask_lo, on_hi, on_lo, 0, crc]
+// port_mask: which ports to update (bit 0 = D1, bit 15 = D16)
+// on_mask: for selected ports, which to turn ON (1) vs OFF (0)
+void callback_set_multi_port_mask()
+{
+    uint16_t port_mask = (uint16_t(buffer_rx[2]) << 8) | uint16_t(buffer_rx[3]);
+    uint16_t on_mask = (uint16_t(buffer_rx[4]) << 8) | uint16_t(buffer_rx[5]);
+
+    for (int i = 0; i < NUM_ILLUMINATION_PORTS; i++)
+    {
+        if (port_mask & (1 << i))  // If this port is selected
+        {
+            if (on_mask & (1 << i))
+                turn_on_port(i);
+            else
+                turn_off_port(i);
+        }
+        // Ports not in port_mask are left unchanged
+    }
+}
+
+// Command byte layout: [cmd_id, 39, 0, 0, 0, 0, 0, crc]
+void callback_turn_off_all_ports()
+{
+    turn_off_all_ports();
+}

firmware/controller/src/commands/light_commands.h

@@ -9,4 +9,12 @@ void callback_set_illumination();
 void callback_set_illumination_led_matrix();
 void callback_set_illumination_intensity_factor();
 
+// Multi-port illumination commands (firmware v1.0+)
+void callback_set_port_intensity();
+void callback_turn_on_port();
+void callback_turn_off_port();
+void callback_set_port_illumination();
+void callback_set_multi_port_mask();
+void callback_turn_off_all_ports();
+
 #endif // LIGHT_COMMANDS_H

firmware/controller/src/constants.h

@@ -3,6 +3,14 @@
 
 #include "constants_protocol.h"
 
+/***************************************************************************************************/
+/**************************************** Firmware Version *****************************************/
+/***************************************************************************************************/
+// Version is sent in response byte 22 as nibble-encoded: high nibble = major, low nibble = minor
+// Version 1.0 = first version with multi-port illumination support
+#define FIRMWARE_VERSION_MAJOR 1
+#define FIRMWARE_VERSION_MINOR 0
+
 #include "def/def_v1.h"
 
 #include "tmc/TMC4361A_TMC2660_Utils.h"

firmware/controller/src/constants_protocol.h

@@ -60,6 +60,18 @@ static const int SEND_HARDWARE_TRIGGER = 30;
 static const int SET_STROBE_DELAY = 31;
 static const int SET_AXIS_DISABLE_ENABLE = 32;
 static const int SET_TRIGGER_MODE = 33;
+
+// Multi-port illumination commands (firmware v1.0+)
+// Separate commands (matches existing SET_ILLUMINATION pattern)
+static const int SET_PORT_INTENSITY = 34;      // Set DAC intensity for specific port only
+static const int TURN_ON_PORT = 35;            // Turn on GPIO for specific port
+static const int TURN_OFF_PORT = 36;           // Turn off GPIO for specific port
+// Combined command (convenience)
+static const int SET_PORT_ILLUMINATION = 37;   // Set intensity + on/off in one command
+// Multi-port commands
+static const int SET_MULTI_PORT_MASK = 38;     // Set on/off for multiple ports (partial update)
+static const int TURN_OFF_ALL_PORTS = 39;      // Turn off all illumination ports
+
 static const int SET_PIN_LEVEL = 41;
 static const int INITFILTERWHEEL_W2 = 252;
 static const int INITFILTERWHEEL = 253;

firmware/controller/src/functions.cpp

@@ -207,6 +207,12 @@ CRGB matrix[NUM_LEDS] = {0};
 void turn_on_illumination()
 {
   illumination_is_on = true;
+
+  // Update per-port state for D1-D5 sources (backward compatibility with new multi-port tracking)
+  int port_index = illumination_source_to_port_index(illumination_source);
+  if (port_index >= 0)
+    illumination_port_is_on[port_index] = true;
+
   switch (illumination_source)
   {
     case ILLUMINATION_SOURCE_LED_ARRAY_FULL:
@@ -263,6 +269,11 @@ void turn_on_illumination()
 
 void turn_off_illumination()
 {
+  // Update per-port state for D1-D5 sources (backward compatibility with new multi-port tracking)
+  int port_index = illumination_source_to_port_index(illumination_source);
+  if (port_index >= 0)
+    illumination_port_is_on[port_index] = false;
+
   switch(illumination_source)
   {
     case ILLUMINATION_SOURCE_LED_ARRAY_FULL:
@@ -317,6 +328,12 @@ void set_illumination(int source, uint16_t intensity)
 {
   illumination_source = source;
   illumination_intensity = intensity * illumination_intensity_factor;
+
+  // Update per-port intensity for D1-D5 sources (backward compatibility with new multi-port tracking)
+  int port_index = illumination_source_to_port_index(source);
+  if (port_index >= 0)
+    illumination_port_intensity[port_index] = intensity;
+
   switch (source)
   {
     case ILLUMINATION_D1:
@@ -349,6 +366,99 @@ void set_illumination_led_matrix(int source, uint8_t r, uint8_t g, uint8_t b)
     turn_on_illumination(); //update the illumination
 }
 
+/***************************************************************************************************/
+/********************************** Multi-port illumination control ********************************/
+/***************************************************************************************************/
+
+// illumination_source_to_port_index() is provided by utils/illumination_mapping.h
+// to ensure firmware and tests use the same mapping logic.
+
+// Gets GPIO pin for port index (0-15), returns -1 for unsupported ports
+int port_index_to_pin(int port_index)
+{
+  switch (port_index)
+  {
+    case 0: return PIN_ILLUMINATION_D1;
+    case 1: return PIN_ILLUMINATION_D2;
+    case 2: return PIN_ILLUMINATION_D3;
+    case 3: return PIN_ILLUMINATION_D4;
+    case 4: return PIN_ILLUMINATION_D5;
+    // Ports 5-15 can be added here as hardware expands
+    default: return -1;
+  }
+}
+
+// Gets DAC channel for port index (0-15), returns -1 for unsupported ports
+static int port_index_to_dac_channel(int port_index)
+{
+  // Currently ports 0-4 map directly to DAC channels 0-4
+  if (port_index >= 0 && port_index < 5)
+    return port_index;
+  return -1;
+}
+
+void turn_on_port(int port_index)
+{
+  if (port_index < 0 || port_index >= NUM_ILLUMINATION_PORTS)
+    return;
+
+  int pin = port_index_to_pin(port_index);
+  if (pin < 0)
+    return;
+
+  if (INTERLOCK_OK())
+  {
+    digitalWrite(pin, HIGH);
+    illumination_port_is_on[port_index] = true;
+  }
+}
+
+void turn_off_port(int port_index)
+{
+  if (port_index < 0 || port_index >= NUM_ILLUMINATION_PORTS)
+    return;
+
+  int pin = port_index_to_pin(port_index);
+  if (pin < 0)
+    return;
+
+  digitalWrite(pin, LOW);
+  illumination_port_is_on[port_index] = false;
+}
+
+// Set DAC intensity for a specific port without changing on/off state.
+// The intensity is scaled by illumination_intensity_factor before being sent to DAC.
+// The unscaled value is stored in illumination_port_intensity[] for reference.
+void set_port_intensity(int port_index, uint16_t intensity)
+{
+  if (port_index < 0 || port_index >= NUM_ILLUMINATION_PORTS)
+    return;
+
+  int dac_channel = port_index_to_dac_channel(port_index);
+  if (dac_channel < 0)
+    return;
+
+  uint16_t scaled_intensity = intensity * illumination_intensity_factor;
+  set_DAC8050x_output(dac_channel, scaled_intensity);
+  illumination_port_intensity[port_index] = intensity;  // Store unscaled for reference
+}
+
+void turn_off_all_ports()
+{
+  for (int i = 0; i < NUM_ILLUMINATION_PORTS; i++)
+  {
+    int pin = port_index_to_pin(i);
+    if (pin >= 0)
+    {
+      digitalWrite(pin, LOW);
+      illumination_port_is_on[i] = false;
+    }
+  }
+  // Also turn off LED matrix if it was on
+  clear_matrix(matrix);
+  illumination_is_on = false;
+}
+
 void ISR_strobeTimer()
 {
   for (int camera_channel = 0; camera_channel < 4; camera_channel++)

firmware/controller/src/functions.h

@@ -3,6 +3,7 @@
 
 #include "constants.h"
 #include "globals.h"
+#include "utils/illumination_mapping.h"
 
 #include <Arduino.h>
 #include <SPI.h>
@@ -54,6 +55,16 @@ void set_illumination(int source, uint16_t intensity);
 void set_illumination_led_matrix(int source, uint8_t r, uint8_t g, uint8_t b);
 void ISR_strobeTimer();
 
+// Multi-port illumination control
+// illumination_source_to_port_index() is provided by utils/illumination_mapping.h
+// Gets GPIO pin for port index, returns -1 for invalid port
+int port_index_to_pin(int port_index);
+// Per-port control functions (interlock checked for turn_on)
+void turn_on_port(int port_index);
+void turn_off_port(int port_index);
+void set_port_intensity(int port_index, uint16_t intensity);
+void turn_off_all_ports();
+
 /***************************************************************************************************/
 /******************************************* joystick **********************************************/
 /***************************************************************************************************/

firmware/controller/src/globals.cpp

@@ -131,8 +131,17 @@ bool enable_filterwheel_w2 = false;
 /***************************************************************************************************/
 int illumination_source = 0;
 uint16_t illumination_intensity = 65535;
+// Illumination intensity scaling factor - scales DAC output for different hardware:
+//   0.6 = Squid LEDs (0-1.5V output range)
+//   0.8 = Squid laser engine (0-2V output range)
+//   1.0 = Full range (0-2.5V output, when DAC gain is 1 instead of 2)
+// This factor is applied to ALL illumination commands (legacy and multi-port).
 float illumination_intensity_factor = 0.6;
 uint8_t led_matrix_r = 0;
 uint8_t led_matrix_g = 0;
 uint8_t led_matrix_b = 0;
 bool illumination_is_on = false;
+
+// Multi-port illumination control (all ports off and at zero intensity by default)
+bool illumination_port_is_on[NUM_ILLUMINATION_PORTS] = {false};
+uint16_t illumination_port_intensity[NUM_ILLUMINATION_PORTS] = {0};

firmware/controller/src/globals.h

@@ -140,4 +140,9 @@ extern uint8_t led_matrix_g;
 extern uint8_t led_matrix_b;
 extern bool illumination_is_on;
 
+// Multi-port illumination control (supports up to 16 ports D1-D16)
+#define NUM_ILLUMINATION_PORTS 16
+extern bool illumination_port_is_on[NUM_ILLUMINATION_PORTS];
+extern uint16_t illumination_port_intensity[NUM_ILLUMINATION_PORTS];
+
 #endif // GLOBALS_H

firmware/controller/src/serial_communication.cpp

@@ -72,6 +72,9 @@ void send_position_update()
     buffer_tx[18] &= ~ (1 << BIT_POS_JOYSTICK_BUTTON); // clear the joystick button bit
     buffer_tx[18] = buffer_tx[18] | joystick_button_pressed << BIT_POS_JOYSTICK_BUTTON;
 
+    // Firmware version in byte 22: high nibble = major, low nibble = minor
+    buffer_tx[22] = (FIRMWARE_VERSION_MAJOR << 4) | (FIRMWARE_VERSION_MINOR & 0x0F);
+
    // Calculate and fill out the checksum.  NOTE: This must be after all other buffer_tx modifications are done!
    uint8_t checksum = crc8ccitt(buffer_tx, MSG_LENGTH - 1);
    buffer_tx[MSG_LENGTH - 1] = checksum;

firmware/controller/src/utils/illumination_mapping.h

@@ -0,0 +1,59 @@
+/**
+ * Illumination port mapping utilities.
+ *
+ * Pure C++ utility functions for mapping between legacy illumination source
+ * codes and port indices. No Arduino/hardware dependencies.
+ */
+
+#ifndef ILLUMINATION_MAPPING_H
+#define ILLUMINATION_MAPPING_H
+
+#include "../constants_protocol.h"
+
+// Number of illumination ports supported
+#define NUM_ILLUMINATION_PORTS 16
+
+/**
+ * Map legacy illumination source code to port index.
+ *
+ * Legacy source codes are non-sequential for historical API compatibility:
+ *   D1 = 11, D2 = 12, D3 = 14, D4 = 13, D5 = 15
+ *
+ * Port indices are sequential: 0=D1, 1=D2, 2=D3, 3=D4, 4=D5
+ *
+ * @param source Legacy illumination source code (11-15)
+ * @return Port index (0-4), or -1 for unknown source codes
+ */
+inline int illumination_source_to_port_index(int source)
+{
+    switch (source)
+    {
+        case ILLUMINATION_D1: return 0;  // 11 -> 0
+        case ILLUMINATION_D2: return 1;  // 12 -> 1
+        case ILLUMINATION_D3: return 2;  // 14 -> 2 (non-sequential!)
+        case ILLUMINATION_D4: return 3;  // 13 -> 3 (non-sequential!)
+        case ILLUMINATION_D5: return 4;  // 15 -> 4
+        default: return -1;  // Unknown source
+    }
+}
+
+/**
+ * Map port index to legacy illumination source code.
+ *
+ * @param port_index Port index (0-4)
+ * @return Legacy source code (11-15), or -1 for invalid port index
+ */
+inline int port_index_to_illumination_source(int port_index)
+{
+    switch (port_index)
+    {
+        case 0: return ILLUMINATION_D1;  // 0 -> 11
+        case 1: return ILLUMINATION_D2;  // 1 -> 12
+        case 2: return ILLUMINATION_D3;  // 2 -> 14
+        case 3: return ILLUMINATION_D4;  // 3 -> 13
+        case 4: return ILLUMINATION_D5;  // 4 -> 15
+        default: return -1;  // Invalid port
+    }
+}
+
+#endif // ILLUMINATION_MAPPING_H