The Harp protocol has no way of indicating to the PC that the device is in an error state. Currently, the only way to do this is through device visual indicators. It looks like an implicit error state may or may not be represented in the OPERATION_CTRL register, but it is not explicit. I propose that we include an error state in the op_mode bits of the OPERATION_CTRL register to provide a way for the PC to read the state of the device
Motivation
It would be useful for devices to be able to communicate to the PC that they are in some sort of error state. Currently, there is no way to do this from the protocol level although the spec declares that a hardware LED should blink at a specified interval. In most cases the LED blink interval represents the internal op mode state except when a critical error occurs. This critical error state should be fully represented and readable in a register too.
Plenty of real-world cases exist where the device could be in some firmware-diagnoseable error state that could be checked from the PC. I propose that an error state be represented as a readable register, rather than solely be flagged as an LED blink interval.
As for what "error" means, that can be up-to-the device. But one easy use-case would be to give the PC a consistent, rather than device-specific, way to query that all hardware is in a non-error state before running an experiment.
Detailed Design
The op_mode bit field seems like a reasonable place to indicate the device state. Currently there are four states, but one is flagged as Reserved. If this Reserved state is actually unused, then using it to represent the ERROR state would be ideal since we would not need to add/shift any bitfields around.
If this Reserved state is unusable, then the next significant bit appears to be unused. We could reserve this bit for op_modes, giving us 8 total possible states. This is also a pretty ideal implementation since we don't have to add/shift any other bitfields around.
It's also worth considering whether entering the error state should also emit an EVENT. I think this behavior is nice-to-have, but my minimum request would be simply to have the error state be readable as a register.
Drawbacks
It's worth mentioning that existing implementations may not be able to easily add this feature. Nevertheless, this feature need not be required--especially since not all device failure modes can be caught by firmware in the first place.
Alternatives
For devices that are in some sort of error state, we could devote one additional App register per device to indicating the device's state. This has the benefit that this app register could be more granular, possibly indicating what kind of error has happened. But the advantage of using a core register is that we have a common way to check every device in a multi-device configuration.
Unresolved Questions
Should the Harp Protocol assume specific hardware as necessary for a full implementation?
Currently, the spec references the behavior of a status LED, and the status LED is the only way to indicate that the device is in a firmware-catchable error state.
A few places indicate bits as "Reserved." For people developing applications, does this mean that we cannot use them, or that they are unused?
Summary
The Harp protocol has no way of indicating to the PC that the device is in an error state. Currently, the only way to do this is through device visual indicators. It looks like an implicit error state may or may not be represented in the OPERATION_CTRL register, but it is not explicit. I propose that we include an error state in the op_mode bits of the OPERATION_CTRL register to provide a way for the PC to read the state of the device
Motivation
It would be useful for devices to be able to communicate to the PC that they are in some sort of error state. Currently, there is no way to do this from the protocol level although the spec declares that a hardware LED should blink at a specified interval. In most cases the LED blink interval represents the internal op mode state except when a critical error occurs. This critical error state should be fully represented and readable in a register too.
Plenty of real-world cases exist where the device could be in some firmware-diagnoseable error state that could be checked from the PC. I propose that an error state be represented as a readable register, rather than solely be flagged as an LED blink interval.
As for what "error" means, that can be up-to-the device. But one easy use-case would be to give the PC a consistent, rather than device-specific, way to query that all hardware is in a non-error state before running an experiment.
Detailed Design
The op_mode bit field seems like a reasonable place to indicate the device state. Currently there are four states, but one is flagged as Reserved. If this Reserved state is actually unused, then using it to represent the ERROR state would be ideal since we would not need to add/shift any bitfields around.
If this Reserved state is unusable, then the next significant bit appears to be unused. We could reserve this bit for op_modes, giving us 8 total possible states. This is also a pretty ideal implementation since we don't have to add/shift any other bitfields around.
It's also worth considering whether entering the error state should also emit an EVENT. I think this behavior is nice-to-have, but my minimum request would be simply to have the error state be readable as a register.
Drawbacks
It's worth mentioning that existing implementations may not be able to easily add this feature. Nevertheless, this feature need not be required--especially since not all device failure modes can be caught by firmware in the first place.
Alternatives
For devices that are in some sort of error state, we could devote one additional App register per device to indicating the device's state. This has the benefit that this app register could be more granular, possibly indicating what kind of error has happened. But the advantage of using a core register is that we have a common way to check every device in a multi-device configuration.
Unresolved Questions
Design Meetings
n/a