From 41d3e3a9addfb0c126dcf16990a3dad90bc4c343 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 3 Nov 2015 19:37:05 +0200 Subject: [PATCH] Fully describe behavior of Pin.value() and Pin.value(x) in different modes, as well as clarificatiosn for other Pin methods. --- Hardware-API.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/Hardware-API.md b/Hardware-API.md index 9ab84cd..ec15fea 100644 --- a/Hardware-API.md +++ b/Hardware-API.md @@ -147,19 +147,24 @@ As specified above, Pin class allows to set alternate function for particular pi ### Methods -Do we really need 3 ways to set the value? +TOD: Do we really need 2+ ways to set the value? -- `pin.init(...)` re init. -- `pin.value()` NOHEAP; get value (returns 1 or 0). See the note below. -- `pin.value(x)` NOHEAP; set value (value can be any valid Boolean expression) -- `pin()` NOHEAP; fast method to get the value of the pin. See the note below. -- `pin(value)` NOHEAP; fast method to set the value of the pin. -- `pin.toggle()` NOHEAP - -**Note:** When the mode is `Pin.OPEN_DRAIN`, it must be possible to read the input value of the Pin. +- `pin.init(...)` - (Re)initinialize a pin, accepts the same parameters as constructor, except `id`. +- `pin.value()` NOHEAP - Get pin value (returns 1 or 0). Behavior depends on the mode of a pin: + - `Pin.IN` - Returns the actual input value currently present on a pin. + - `Pin.OUT` - Undefined. MAY return value stored in the output buffer of a pin. + - `Pin.OPEN_DRAIN` - If pin is in "0" state, undefined. MAY return value stored in the output buffer of a pin (i.e. 0). Or MAY return actual input value on a pin. Otherwise, if pin is in "1", MUST return actual input value on a pin. (Note that if open-drain pin is in 0 state, entire bus to which pin is connected, expected to be in 0 state, so there's little point to read actual input value; the only reason for another value in this case would be voltage conflict on a bus, which is usually a hardware malfunction and in some cases may lead to physical damage of a pin). +- `pin.value(x)` NOHEAP - Set output value of a pin (value can be any valid expression, which is cast to True/False valur for 1/0 output value respectively). Exact behavior depends on the pin mode: + - `Pin.IN` - Value is stored in the output buffer for a pin. Pin state doesn't change (it keeps being in high-impedance state, as required for IN mode). The stored value will become active on a pin as soon as it is changed to OUT or OPEN_DRAIN mode. + - `Pin.OUT` - Pin is set to the `x` value immediately. + - `Pin.OPEN_DRAIN` - If value is "0", ping is set to low state. Otherwise, it is set to high-impedance state. +- `pin.out_value()` NOHEAP, optional - Return value stored in the output buffer of a pin, regardless of its mode. +- `pin()` NOHEAP - Fast method to get the value of the pin. Fully equivalent to `Pin.value()`. +- `pin(x)` NOHEAP - Fast method to set the value of the pin. Fully equivalent to `Pin.value(x)`. +- `pin.toggle()` NOHEAP, optional - Toggle output value of a pin. **Getters and setters** -- `pin.id()` NOHEAP; get only. - need to clarify what this really returns. I'm assuming a board ID. +- `pin.id()` NOHEAP; get only. - Return ID of a pin. This MAY return `id` as specified in the constructor. Or it MAY return "normalized" software-specific pin ID. - `pin.mode([mode])` NOHEAP - `pin.pull([pull])` NOHEAP - `pin.drive([drive])` NOHEAP