-
Notifications
You must be signed in to change notification settings - Fork 630
Clarify MotorHat disposal/ownership semantics in README #2584
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 3 commits
a68555e
5c613ef
8af576d
9bc2313
dbdd54a
62716ec
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -41,6 +41,55 @@ using (var motorHat = new MotorHat()) | |||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| Check the [ServoMotor documentation](../ServoMotor/README.md) for examples on how to use the ServoMotor class | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ## Resource management (disposing) | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| The `MotorHat` owns all the resources it creates. When you call `CreateDCMotor`, `CreateServoMotor` or `CreatePwmChannel`, the returned object uses PWM channels that belong to the `MotorHat`'s underlying PCA9685 controller. | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| Because of this ownership model: | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| - **Disposing the `MotorHat` is enough.** `MotorHat.Dispose()` stops every channel it handed out and then disposes the underlying PCA9685 (and its I2C device). You do not need to dispose the motors, servos or PWM channels separately. | ||||||||||||||||||||||||||||||
| - **Disposing a motor as well is safe.** Disposing a `DCMotor` created by `CreateDCMotor` only stops its PWM channels; it does not dispose them. Combined with the point above, disposing both the motor and the `MotorHat` will not throw or leave the board in a random state. | ||||||||||||||||||||||||||||||
| - **Order does not matter.** You can dispose the motors before or after the `MotorHat`; the result is the same. | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| The recommended pattern is to keep the objects you need alive for as long as the `MotorHat` and let a single `using` (or `Dispose`) on the `MotorHat` clean everything up: | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ```csharp | ||||||||||||||||||||||||||||||
| using (var motorHat = new MotorHat()) | ||||||||||||||||||||||||||||||
| { | ||||||||||||||||||||||||||||||
| var motor = motorHat.CreateDCMotor(1); | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| motor.Speed = 1; | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| // ... use the motor ... | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| // No need to dispose 'motor' explicitly; disposing 'motorHat' releases it. | ||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| If you wrap the `MotorHat` in your own class, forward disposal to the `MotorHat`. Disposing the individual motors as well is harmless but not required: | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ```csharp | ||||||||||||||||||||||||||||||
| public class PumpController : IDisposable | ||||||||||||||||||||||||||||||
| { | ||||||||||||||||||||||||||||||
| private MotorHat _motorHat = new MotorHat(); | ||||||||||||||||||||||||||||||
| private List<DCMotor> _motors = new List<DCMotor>(); | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| public void Initialize() | ||||||||||||||||||||||||||||||
| { | ||||||||||||||||||||||||||||||
| _motors.Add(_motorHat.CreateDCMotor(1)); | ||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| // ... use the motors ... | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| public void Dispose() | ||||||||||||||||||||||||||||||
| { | ||||||||||||||||||||||||||||||
| // Disposing the MotorHat stops and releases every motor/channel it created. | ||||||||||||||||||||||||||||||
| // Order is not important and disposing the motors as well would be safe. | ||||||||||||||||||||||||||||||
| _motorHat.Dispose(); | ||||||||||||||||||||||||||||||
|
Copilot marked this conversation as resolved.
Outdated
|
||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||
|
Comment on lines
+85
to
+94
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @copilot fix it with correct indent
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done — updated the |
||||||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||||||
| ``` | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ## Support | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| - Up to 4 DC Motors | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
Uh oh!
There was an error while loading. Please reload this page.