feat: Multi-port illumination control + laser port naming refactor

[hongquanli]

Summary

This PR combines two related changes:

1. Laser Port Naming Refactor

• Rename wavelength-based constants (ILLUMINATION_SOURCE_405NM) to port-based names (ILLUMINATION_D1)
• Fix D3/D4 non-sequential source code mapping (D3=14, D4=13)
• Update documentation to clarify "Illumination Control TTL Ports"

2. Multi-Port Illumination Control (NEW)

Enable multiple illumination ports to be ON simultaneously with independent intensities:

Firmware:

• Add per-port state arrays (illumination_port_is_on[], illumination_port_intensity[])
• Add new protocol commands (34-39): SET_PORT_INTENSITY, TURN_ON_PORT, TURN_OFF_PORT, SET_PORT_ILLUMINATION, SET_MULTI_PORT_MASK, TURN_OFF_ALL_PORTS
• Add firmware version reporting in response byte 22 (v1.0)
• Maintain backward compatibility with legacy single-source commands

Python:

• Add Microcontroller methods for multi-port control with port validation
• Add IlluminationController high-level API with state tracking and supports_multi_port() checks
• Add SimSerial simulation support for testing
• Add early firmware version detection during init
• Add centralized source_code_to_port_index() and port_index_to_source_code() mapping functions

Tests:

• 80 firmware tests (PlatformIO/Unity)
• 29 Python tests covering protocol, edge cases, D3/D4 mapping

Documentation:

• Add comprehensive software/docs/illumination-control.md covering:
  • Hardware port mapping (D1-D5 with port indices, source codes, DAC/GPIO)
  • Legacy vs Multi-port API comparison with examples
  • Firmware version requirements
  • Troubleshooting guide
• Document illumination_intensity_factor scaling (0.6=LEDs, 0.8=laser, 1.0=full)
• Document non-blocking nature of Microcontroller methods
• Add class docstring to IlluminationController explaining API choice

Test Plan

• All 29 Python tests pass
• All 80 firmware tests pass
• Hardware tested - All 9 manual tests passed:
  1. ✅ Firmware version detection (v1.0)
  2. ✅ Legacy API backward compatibility
  3. ✅ Single port control (new API)
  4. ✅ Multiple ports ON simultaneously
  5. ✅ D3/D4 non-sequential mapping
  6. ✅ IlluminationController high-level API
  7. ✅ Intensity levels (0-100%)
  8. ✅ Rapid switching (20 cycles)
  9. ✅ Error handling (invalid port rejection)

Files Changed

Firmware

• firmware/controller/src/constants_protocol.h - New command codes
• firmware/controller/src/globals.h/cpp - Per-port state arrays
• firmware/controller/src/functions.h/cpp - Port control functions
• firmware/controller/src/commands/light_commands.h/cpp - Command callbacks
• firmware/controller/src/illumination_mapping.h - Source code ↔ port mapping

Python

• software/control/_def.py - New CMD_SET constants, mapping functions
• software/control/microcontroller.py - Multi-port MCU methods
• software/control/lighting.py - IlluminationController enhancements

Documentation

• software/docs/illumination-control.md - Comprehensive guide (NEW)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refactors laser/illumination naming to be port-based (D1–D5), fixes the D3/D4 mapping, and adds a full multi-port illumination control path (firmware + Python + simulation) with firmware version reporting and extensive tests.

Changes:

• Introduces new multi-port illumination commands and state on the firmware side (per-port on/off and intensity, mask operations, port mapping utilities) plus nibble-encoded firmware version reporting.
• Adds Python-side support: Microcontroller multi-port methods with firmware-version detection, an IlluminationController multi-port API, and SimSerial enhancements to simulate the new protocol and state.
• Refactors illumination constants and configuration to use port-based names (ILLUMINATION_D1–D5) with legacy wavelength-based aliases, fixes the D3/D4 non-sequential mapping, and updates protocol/tests/configs accordingly.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
software/tests/test_multiport_illumination_protocol.py	Adds protocol-level tests to assert Python multi-port commands (bytes, masks, endian-ness) match firmware expectations, including D3/D4 mapping and legacy/new command interaction.
software/tests/test_multiport_illumination_edge_cases.py	Adds edge-case/integration tests for intensities, command layouts, legacy vs new command interactions, mapping utilities, firmware version behavior, and IlluminationController validation.
software/tests/test_multiport_illumination_bugs.py	Adds focused tests targeting likely multi-port bugs (D3/D4 mapping, combined commands, mask overlap, sequencing, controller/MCU sync, firmware version support).
software/tests/test_multiport_illumination.py	Adds higher-level tests for multi-port illumination behavior across SimSerial, Microcontroller, and IlluminationController, including simultaneous ports and invalid indices.
software/tests/control/test_firmware_protocol.py	Extends firmware/protocol consistency tests to cover new port-based illumination codes, legacy wavelength aliases, and bidirectional consistency across LED patterns and D1–D5 names.
software/machine_configs/illumination_channel_config.yaml	Updates machine YAML to correct D3/D4 controller port mapping (D3=14/561nm, D4=13/638nm) and channel controller_port references.
software/control/models/illumination_config.py	Updates IlluminationChannelConfig default controller_port_mapping to use ILLUMINATION_CODE constants for D1–D5 and LED patterns rather than raw integers.
software/control/microcontroller.py	Adds multi-port command constants to logging, extends SimSerial with multi-port state, legacy<->multi-port sync, and firmware version encoding; adds Microcontroller multi-port methods, firmware-version tracking/detection, and supports_multi_port().
software/control/lighting.py	Adds NUM_ILLUMINATION_PORTS, imports/exports port/source mapping helpers, defines IlluminationController’s multi-port API including per-port state tracking and convenience operations (turn on multiple, get active ports).
software/control/core/core.py	Changes ImageArrayDisplayWindow.display_image to use source_code_to_port_index so D1–D5 routing respects the non-sequential D3/D4 source codes.
software/control/_def.py	Introduces multi-port command codes, port-based illumination codes (ILLUMINATION_D1–D5), legacy wavelength aliases, ILLUMINATION_PORT indices, source↔port mapping helpers, and documents illumination intensity scaling factor.
firmware/controller/test/test_protocol/test_protocol.cpp	Extends protocol unit tests to include MOVE_W2, new multi-port commands (uniqueness, range), axis ID for W2, and validates D1–D5 codes and wavelength aliases.
firmware/controller/test/test_illumination_utils/test_illumination_utils.cpp	Adds unit tests for intensity↔DAC conversions, firmware version nibble encode/decode, and port-mask helper utilities.
firmware/controller/test/test_illumination_mapping/test_illumination_mapping.cpp	Adds tests for C++ illumination source↔port index mapping, including non-sequential D3/D4 and round-trip consistency.
firmware/controller/test/test_command_layout/test_command_layout.cpp	Adds tests validating byte layouts of all new multi-port commands and the response packet layout (including version byte position).
firmware/controller/src/utils/illumination_utils.h	Introduces C++ inline helpers for intensity conversions, firmware version encoding/decoding, and port mask operations usable in tests and firmware.
firmware/controller/src/utils/illumination_mapping.h	Adds C++ inline mapping utilities for legacy illumination source codes to port indices and back, plus NUM_ILLUMINATION_PORTS for tests/utilities.
firmware/controller/src/serial_communication.cpp	Writes nibble-encoded firmware version into response byte 22 before CRC so the host can detect firmware version.
firmware/controller/src/init.cpp	Switches laser-related pin initialization from legacy names to new PIN_ILLUMINATION_D* and PIN_ILLUMINATION_INTERLOCK constants, keeping behavior but using port-based naming.
firmware/controller/src/globals.h	Declares NUM_ILLUMINATION_PORTS and per-port illumination_port_is_on/illumination_port_intensity globals for firmware multi-port tracking.
firmware/controller/src/globals.cpp	Initializes new global multi-port illumination state arrays and documents the global illumination_intensity_factor semantics.
firmware/controller/src/functions.h	Declares new multi-port illumination functions (source→port mapping, port→pin, per-port on/off/intensity, turn_off_all_ports) for use by command callbacks.
firmware/controller/src/functions.cpp	Implements legacy illumination using new D1–D5 names and adds multi-port control helpers (source→port index, port→pin, per-port on/off/intensity, and a turn_off_all_ports that clears all ports and LED matrix).
firmware/controller/src/constants_protocol.h	Defines new multi-port command IDs, D1–D5 port-based illumination constants, and legacy wavelength aliases in the firmware protocol constants.
firmware/controller/src/constants.h	Adds firmware version macros, introduces PIN_ILLUMINATION_D*/PIN_ILLUMINATION_INTERLOCK pin assignments, and defines legacy pin aliases plus an updated INTERLOCK_OK() macro.
firmware/controller/src/commands/light_commands.h	Declares callbacks for the new multi-port illumination commands.
firmware/controller/src/commands/light_commands.cpp	Implements callbacks for each new multi-port command and wires them to the underlying per-port helper functions.
firmware/controller/src/commands/commands.cpp	Registers the new multi-port command callbacks in the central cmd_map.
firmware/controller/main_controller_teensy41.ino	Updates the main loop’s interlock handling to use the new port-based pin names and to turn off all D1–D5 TTL pins when the interlock is triggered.

Comments suppressed due to low confidence (1)

firmware/controller/src/functions.cpp:325

• turn_off_illumination() only clears the state and GPIO for the currently selected illumination_source, but does not turn off any other TTL ports that may have been enabled via the new multi-port APIs, while the SimSerial implementation and Python tests treat TURN_OFF_ILLUMINATION as turning all ports off. This creates a divergence between simulated behavior and real firmware (and can leave additional ports on when callers expect everything off), especially in mixed legacy/new-command scenarios. Consider delegating legacy TURN_OFF_ILLUMINATION to a helper that also invokes turn_off_all_ports() (or otherwise iterates all ports) so hardware behavior matches the multi-port model and the Python tests' expectations.

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:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFT_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_RIGHT_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFTB_RIGHTR:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LOW_NA:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFT_DOT:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_RIGHT_DOT:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_TOP_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_BOTTOM_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_EXTERNAL_FET:
      break;
    case ILLUMINATION_D1:
      digitalWrite(PIN_ILLUMINATION_D1, LOW);
      break;
    case ILLUMINATION_D2:
      digitalWrite(PIN_ILLUMINATION_D2, LOW);
      break;
    case ILLUMINATION_D3:
      digitalWrite(PIN_ILLUMINATION_D3, LOW);
      break;
    case ILLUMINATION_D4:
      digitalWrite(PIN_ILLUMINATION_D4, LOW);
      break;
    case ILLUMINATION_D5:
      digitalWrite(PIN_ILLUMINATION_D5, LOW);
      break;
  }
  illumination_is_on = false;
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The illumination_source_to_port_index mapping logic here duplicates the mapping implemented in utils/illumination_mapping.h, which defines the same function (with identical semantics) as an inline utility for tests and other code. Duplicating this mapping in two places makes it easy for the firmware implementation and the tested mapping to drift apart over time; it would be more maintainable to reuse the header utility (or a shared helper) in the firmware implementation rather than re-encoding the mapping here.

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - functions.cpp now includes utils/illumination_mapping.h and uses the shared implementation instead of duplicating the mapping logic.

[Copilot]

The high-level multi-port methods (set_port_intensity, turn_on_port, turn_off_port, set_port_illumination, turn_on_multiple_ports, turn_off_all_ports) call the new MCU commands unconditionally without checking microcontroller.supports_multi_port(). This means that if these APIs are used against legacy firmware (where supports_multi_port() is False), they will still send unsupported command codes, leading to confusing behavior instead of a clear, early error; given that firmware version detection and supports_multi_port() were added, these methods should check support and raise a descriptive exception when multi-port is not available.

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Added _check_multi_port_support() helper method called by all multi-port methods. Raises RuntimeError with clear message if firmware doesn't support multi-port commands.

[Copilot]

Variable initial is not used.

Suggested change

initial = mcu.firmware_version

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Added assertion to use the initial variable: assert isinstance(initial, tuple) and len(initial) == 2

[Copilot]

Import of 'source_code_to_port_index' is not used.
Import of 'port_index_to_source_code' is not used.

Suggested change

	__reexported_mapping_functions = (source_code_to_port_index, port_index_to_source_code)

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Removed the re-exports. The canonical location is control._def, so re-exporting from lighting.py added confusion without value.

[Copilot]

Import of 'ILLUMINATION_PORT' is not used.

Suggested change

	from control._def import CMD_SET, ILLUMINATION_PORT, ILLUMINATION_CODE
	from control._def import CMD_SET, ILLUMINATION_CODE

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Removed unused ILLUMINATION_PORT import.

[Copilot]

Import of 'NUM_ILLUMINATION_PORTS' is not used.

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Removed unused NUM_ILLUMINATION_PORTS import.

[Copilot]

Import of 'ILLUMINATION_PORT' is not used.

Suggested change

	from control._def import CMD_SET, ILLUMINATION_PORT, ILLUMINATION_CODE
	from control._def import CMD_SET, ILLUMINATION_CODE

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Removed unused ILLUMINATION_PORT import.

[Copilot]

Import of 'NUM_ILLUMINATION_PORTS' is not used.

Suggested change

	from control.lighting import IlluminationController, NUM_ILLUMINATION_PORTS
	from control.lighting import IlluminationController

[hongquanli]

[Claude Code] Fixed in commit 1d4f483 - Removed unused NUM_ILLUMINATION_PORTS import.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

firmware/controller/src/functions.cpp:325

• turn_off_illumination only clears the active LED pattern and toggles the single TTL port corresponding to illumination_source, but it does not interact with the new illumination_port_is_on array beyond the current source or call turn_off_all_ports(). This means that after using the new per-port APIs to turn on multiple ports, calling the legacy TURN_OFF_ILLUMINATION command will leave other ports still on in firmware, diverging from the SimSerial behavior and the Python tests which expect it to turn off all ports. Consider updating this function (or the legacy callback) to delegate to turn_off_all_ports() for TTL ports so that legacy and new illumination paths stay consistent and all ports are safely turned off.

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:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFT_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_RIGHT_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFTB_RIGHTR:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LOW_NA:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_LEFT_DOT:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_RIGHT_DOT:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_TOP_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_ARRAY_BOTTOM_HALF:
      clear_matrix(matrix);
      break;
    case ILLUMINATION_SOURCE_LED_EXTERNAL_FET:
      break;
    case ILLUMINATION_D1:
      digitalWrite(PIN_ILLUMINATION_D1, LOW);
      break;
    case ILLUMINATION_D2:
      digitalWrite(PIN_ILLUMINATION_D2, LOW);
      break;
    case ILLUMINATION_D3:
      digitalWrite(PIN_ILLUMINATION_D3, LOW);
      break;
    case ILLUMINATION_D4:
      digitalWrite(PIN_ILLUMINATION_D4, LOW);
      break;
    case ILLUMINATION_D5:
      digitalWrite(PIN_ILLUMINATION_D5, LOW);
      break;
  }
  illumination_is_on = false;
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

display_image only handles port_index values 0, 1, and 3; when source_code_to_port_index(illumination_source) returns 2 (D3) or 4 (D5), the function falls through without updating any widget, so frames for those ports are never displayed. To preserve the previous behavior where unmapped sources defaulted to graphics_widget_1, you should either add explicit branches for port_index == 2/4 or add a final else that routes all remaining valid D ports to a sensible widget.

Suggested change

	self.graphics_widget_4.img.setImage(image, autoLevels=False)
	self.graphics_widget_4.img.setImage(image, autoLevels=False)
	else:
	# Any remaining valid D ports (e.g., D3/D5) fall back to default widget
	self.graphics_widget_1.img.setImage(image, autoLevels=False)

[hongquanli]

[Claude Code] Fixed in commit f37b88c - added else clause to handle D3 (port_index=2) and D5 (port_index=4), falling back to graphics_widget_1.