[Microbit-Python] Units for API functions.

[Damien George]

Hi Mark,

I think brightness should range from 0-9 inclusive.  Reason: that's 10
values, it's Pythonic (range(10)), and most importantly you can encode
an image in a string using single digits: "09990\n09090\n...".

The compass outputs a heading in degrees.

The accelerometer is (or should be) in milli-g's.  Ie 1000=9.8m/s^2.

I think that arguments which correspond to continuous numeric values
should allow int or float (with implicit truncation of float to int),
while others should be int only.  Eg set_pixel(x,y) should have x,y
int only, yet write_analog(v) should allow v to be a float.

Cheers,
Damien.


On Tue, Sep 29, 2015 at 10:56 PM, Mark Shannon <mark at hotpy.org> wrote:
> 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.
>
>
>
> _______________________________________________
> Microbit mailing list
> Microbit at python.org
> https://mail.python.org/mailman/listinfo/microbit
>