Add developer documentation for hardware framework #379
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #379 +/- ##
=======================================
Coverage 79.04% 79.04%
=======================================
Files 56 56
Lines 2925 2925
=======================================
Hits 2312 2312
Misses 613 613 ☔ View full report in Codecov by Sentry. |
alexdewar
force-pushed
the
hardware_documentation
branch
from
40746cf
to
d1d200e
Compare
docs/hardware.md
Outdated
| ### Device parameters | ||
|
|
||
| Devices can also require additional parameters to be specified by the user, such as port | ||
| and baudrate for serial devices. Details about these parameters are set in an | ||
| `__init_subclass__()` method for the class. These parameters will be passed as arguments | ||
| to the device type's constructor when it is opened. |
There was a problem hiding this comment.
This is very unclear - or at least ambiguous. Are these parameters passed to the __init_subclass__ method, and therefore need to be included in the subclass definition, or are they pass when constructing the object? And example, as you have done above, will be useful.
| Device types also need to define their own message types for communication. For example, | ||
| the `StepperMotorBase` class allows for setting the current angle of the stepper motor | ||
| with a `device.stepper_motor.move.begin` message. |
There was a problem hiding this comment.
It will be useful, I think, to indicate somewhere the list of all possible messages a particular device type handles - either sending or receiving. In the end, pubsub topics are implicit function calls with their own parameters and they should be documented in detail as we do with any other function.
We have never done it before, but given the complexity of the messaging system of FINESSE, it might be worth considering doing something like this https://pypubsub.readthedocs.io/en/v4.0.3/usage/usage_advanced_maintain.html#specify-topic-tree-def, although as most topics are created implicitely based on the device names, I'm not sure how far we can go down this route...
There was a problem hiding this comment.
Makes sense.
The doc you link to looks interesting. I'll see if we can incorporate that way of doing things 😄
There was a problem hiding this comment.
This is a good idea, but I think we should do it later. I've opened an issue for it: #432
Co-authored-by: Daniel Cummins <[email protected]>
alexdewar
force-pushed
the
hardware_documentation
branch
from
e372c9f
to
b4d5d88
Compare
…tion Add developer documentation for hardware framework
This potentially could be more detailed, but hopefully there's enough information in here for would-be contributors to get started.
@CWestICL: Would you mind reviewing this and checking that it makes sense to you? You're currently the target audience for it 😉
Closes #366.