Modifying the base ElectronMicroscope

ElectronMicroscope (asyncroscopy/instruments/electron_microscope/electron_microscope.py) is the vendor-agnostic Tango device. It owns the public @command API and the abstract _helper methods each vendor subclass (e.g. AutoScriptMicroscope) must fill in.

The pattern: a public @command validates input and reads settings from the detector DeviceProxy objects, then delegates to a vendor _helper. Acquisition commands return a Tiled key (a string); the client reads the data back from the Tiled server with that key.

If you’re editing this class, you’re usually doing one of these:

1. Adding or modifying an attribute (Expose new device state clients can read, e.g. stem_mode.)

2. Updating an attribute read/write method (Control how a value is validated, stored, or synced with the vendor API.)

3. Adding or modifying a public command Add a thin @command that validates input, reads any settings from a detector proxy, then calls a vendor _helper. Existing groups:

   • acquisition — acquire_scanned_image, acquire_spectrum, acquire_camera_image, acquire_flucam_image, acquire_scanned_data_advanced

   • beam / optics — place_beam, place_beam_list, blank_beam, unblank_beam, set_defocus / get_defocus, set_image_shift, set_column_valves

   • stage — get_stage, move_stage

   • imaging conditions — set_fov / get_fov, set_screen_current / get_screen_current, auto_focus

4. Adding or changing a vendor _helper contract The _helper methods are the vendor extension points. Add the public @command here, and the _helper it delegates to.

   • Required (declared @abstractmethod — every subclass must implement): _connect, _connect_hardware, _connect_detector_proxies, _acquire_scanned_image, _get_stage, _move_stage, _set_fov / _get_fov, _set_screen_current / _get_screen_current, _auto_focus, _set_image_shift.

   • Optional (default no-op or “unsupported” — override only if the vendor supports it): _acquire_camera_image, _acquire_scanned_data_advanced, _place_beam, _blank_beam, _unblank_beam, _set_defocus / _get_defocus.

   • Note: acquire_spectrum delegates to _acquire_spectrum, which is not declared on the base — it’s defined only in the vendor subclass. If you add a new vendor, you must provide _acquire_spectrum yourself.

5. Changing the return / transport convention Acquisition commands return a Tiled key string; the actual save happens in the vendor helper via save_acquisition (asyncroscopy/data/data_writer.py) and registration via the DATA device (asyncroscopy/data/data.py). See data_integration.md. The legacy get_image_data_cached (returns DevEncoded) is the only remaining byte-over-Tango path.

6. Improving robustness (Connection failures, missing proxies, vendor-API errors, simulation fallback, or state transitions like FAULT / ON / OFF.)