[Microbit-Python] Units for API functions.

[Mark Shannon]

Hi all,

We've all had fun discussing the names of functions in the API,
but what about units?

So far, we have agreed on units for I/O pins and times.

For pin I/O we accept values in the range 0 to 1023, with a unit of 
3.3/1023 volts.
0 to 1023 translates directly to the capability of the DAC/ADC on the 
device.

For measuring time, it seems that milliseconds are the standard.

That leaves brightness, the accelerometer and the compass.

For brightness, I would like to propose using a linear scale of 
*perceived* brightness. Acceptable values would range from 0 to N, where 
N is in the range 10 to ~15.
0 is off. 1 to N are linearly increasing levels of brightness.
The value passed to the underlying C++ layer must be in the range 0 to 
255. Therefore, a brightness of n would translate to roughly K**(n-1), 
where K**(N-1) would be about 255.
Candidates for N are:
10, 10 is a natural limit for kids used to decimal.
11, it goes to 11 :)
15, 15 is the maximum hex digit and about the limit of being able to
distinguish between brightness levels.
(I prefer 11, the bbc iplayer volume goes to 11).

What about ranges/units for the accelerometer or compass?
Does anyone have any thoughts on those?
If they are to be arbitrary, it might make sense to choose 0-1023 for 
consistency with the other I/O.

In terms of the implementation, I would expect that all inputs take ints 
or floats and all outputs return ints. They should be documented as 
"number" throughout.
E.g. Pin.write_analog(x) will take an int or float and be documented as 
taking any number between 0 and 1023.

Cheers,
Mark.

P.S.
If you haven't played with brightnesses, then try the attached program.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: beating_heart.py
Type: text/x-python
Size: 557 bytes
Desc: not available
URL: <https://mail.python.org/mailman/private/microbit/attachments/20150929/442e1a45/attachment.py>