|
| 1 | +API Design Heuristics |
| 2 | +===================== |
| 3 | + |
| 4 | +The API should be Pythonic yet pragmatic. We formulated the following heuristics at PyCon UK 2015. |
| 5 | + |
| 6 | +* If there is only one of a certain type of hardware, we instantiate it and make the resulting object available under the `microbit` namespace. E.g. `microbit.compass`. |
| 7 | +* If there are several of certain types of hardware we enumerate them under a namespace for that type of hardware. E.g. `microbit.buttons.a` |
| 8 | +* We use short, obvious commonly used names for things and avoid acronyms. Ergo, `microbit.io` is renamed to `microbit.pins`. |
| 9 | +* Pins, because they are objects, are names `p0`-`p20` (not uppercase). |
| 10 | +* The `set_analog_interval` method is universal in scope for the pins, so is made available under the `microbit.pins` namespace. |
| 11 | +* Each pin object will only have methods that match its actual capabilities - so if it's a digital only pin, it shouldn't have analog methods. |
| 12 | +* The pin methods are: `write_digital(x)`, `read_digital()`, `write_analog(x)` and `read_analog()`. They're not attributes so they can be used in lambdas and for consistency (everything else is a function). |
| 13 | + |
| 14 | +*** HERE BE DRAGONS *** |
| 15 | + |
| 16 | +* The `microbit.display` object has several related methods to draw things on the display in increasing complexity / capability: `print`, `scroll` and `animate`. |
| 17 | +* The display has two modes: on/off and greyscale. Only 4 or 5 graduations of greyscale are actually visible. We could make these easy to use/remember (0-5???). |
| 18 | +* I can't remember much about the outcome of the discussion about this - I remember having to leave the room / let people in so my memory is fuzzy and I don't trust it. Please revise. |
| 19 | +* It would be possible to implement a sound / music API using the PWM capabilities of the device. Nicholas to flesh this out in public. |
| 20 | +* We need more built-in images in addition to the 20 or so we already have. |
| 21 | +* Suggested Easter eggs: |
| 22 | +1. import love |
| 23 | +2. import antigravity |
| 24 | +3. "Australia" mode (in honour of Damien - everything on the display is upside down to what it should be) |
| 25 | +4. built in animations for common signals - e.g. the heartbeat we already have |
0 commit comments