a-hurst / magneto Goto Github PK

At present, magneto has no support for Rapid or Rapid^2 stimulators. Support can eventually be added in two phases:

1. Adding support for Rapid stimulators to the base Magstim class, allowing the use of these units for basic single-pulse TMS.
2. Adding a dedicated Rapid class that provides an API for the unique rTMS abilities of the unit.

The main barrier to 1) is the requirement of an "unlock code" for establishing serial control over Rapid units with software v9.0 or later. Some options for exposing this to the user could be:

a) Adding an environment variable where the unlock code can be stored, which has the benefit of working across all experiments on a computer, and/or
b) Adding a set_rapid_unlock function for initializing the code in the runtime.

Additionally, we need a way of detecting whether a given stimulator is a Rapid so we can initialize it properly. The easiest method for this is probably checking the software version from the stimulator (BiStim & 200 report V1.9, lowest Rapid version seems to be V7.0), especially since the Rapid API is slightly different depending on the exact software version. However, I'm not sure whether newer BiStims have newer software versions or what the earliest Rapid software versions are (v7.0?) so it might help to have another way of checking. The 'get system version' function has a non-standard return style (null-terminated instead of fixed-length) so will need to be done outside the normal communication loop as a stand-alone function.

Initial steps for Rapid support:

• Add constants for the new functions/responses in the Rapid API
• Add function/method for detecting whether a stimulator is a Rapid
• Add function for determining the software version of the connected stimulator
• Add API for providing Rapid unlock code for newer stimulators (>= v9.0)
• Add minimal bindings for functions required to configure a Rapid into single-pulse mode
• Add basic initialization support for pre-v9.0 Rapids to the single-pulse Magstim class
• Modify the comms thread to support sending "get system status" commands to keep the connection alive instead of "establish remote control" on newer Rapid stimulators (>= v9.0)

Steps for dedicated Rapid class:

• Bind remaining functions in the Rapid API
• Figure out how to support the slight API differences between Rapid versions
• Add code/data for calculating safe operation constraints as per the documentation
• Write public API and documentation for Rapid functionailty

Hardware TODO:

• Get the unlock code for the lab's Rapid so we can actually test
• Check whether 'get params' command still works normally on the Rapid
• Check whether the 'get rapid params' command works on 200/BiStim units (could be used to check if machine is a Rapid, since it doesn't require the unlock code to run)

To achieve better feature parity with MagPy, magneto should have a BiStim class for configuring pulse intervals and the power level for stimulator B. The basics for this are already in place since, but some additional work and creativity is needed for adding a pleasant and robust API for these units.

Steps for dedicated BiStim class:

• Add constants and internal bindings for all BiStim-specifc commands
• Figure out how to check whether the unit is actually a BiStim
• Add public methods for getting/setting Power B
• Add public methods for getting/setting the inter-pulse interval
• Write documentation for BiStim functionality and quirks

Notes:

• BiStim has command for toggling 'high-resolution mode' for the inter-pulse interval, but API-wise it's probably nicer to start with it in a known state and then toggle it when needed.
• Signal is able to identify whether a device is a BiStim based on undocumented serial commands. If I can reverse-engineer these, that should help make things easier.
• Can't set power level to be non-zero in Simultaneous Discharge Mode. Should raise an informative exception if someone tries this.
• Can't set pulse interval to be under 1 ms, even in high-resolution mode. Should raise an exception if someone tries this.