[Microbit-Python] A request for help... fancy designing a Pythonic API that up to 1 million kids would use..?
David Whale
david at thinkingbinaries.com
Sat Aug 29 14:35:59 CEST 2015
Hi All,
Here are the latest TD namespaces and contents, which you should note is
not necessarily the DAL API, so read it a bit with a pinch of salt in
places.
Also I checked both the docs and the latest actual editor and there are
differences, which I have marked as below.
This *might* be the best/most definitive list we have at the moment, at
least!
This is not an attempt to make it Pythonic, only a stake in the ground to
say it is a starting point to move forward from, to raise discussions per
method as to whether to keep consistency or add Pythonic magic (or both, of
course).
Nicholas - is it best for us to converse directly on this, or on the list?
i.e. are there others who would like to be involved, or is it best for some
of us to go off to one side for a bun-fight and report back when we have
something more solid to propose?
KEY
- means removed from latest drop but still in docs
* means appeared in latest drop but not in docs yet
MICROBIT.BASIC NAMESPACE
------------------------
plot image(leds)
show number(value, interval)
show string(text, interval)
show animation(leds, interval)
clear screen()
forever(body)
pause(ms)
MICROBIT.LED NAMESPACE
----------------------
plot(x, y)
unplot(x, y)
point(x, y)->bool
set brightness(value)
fade in(ms)
fade out(ms)
*plot all()
*screenshot->img
*toggle(x, y)
*toggle all()
*brightness()->int
MICROBIT.CONTROL NAMESPACE
--------------------------
in background(body)
*MICROBIT.EVENTS NAMESPACE
-------------------------
{possibly limited to bluetooth only, but they do go on the event bus,
so there might still be a way to get these to action even without BT}
*remote control(event)
* event=[play,pause,stop,next track, previous track, rewind, volume up,
volume down]
*camera(event)
* event=[take photo, start video capture, stop video capture, toggle
front-rear,
* launch photo mode, launch video mode, stop photo mode, stop video mode]
*alert(event)
* event=[display toast, vibrate, play sound, play ringtone, find my phone,
* alarm 1, alarm 2, alarm 3, alarm 4, alarm 5, alarm 6,
*audio recorder(event)
* event=[launch, start capture, stop capture, stop]
*MICROBIT.GAME NAMESPACE
-----------------------
(a standard library already included in the root namespace)
*add life(lives)
*add score(points)
*current time()->number
*level->number
*level up()
*life()->number
*remove life(live)
*score()->number
*set life(value)
*set score(value)
*start countdown(ms)
MICROBIT.INPUT NAMESPACE
------------------------
{note, 'body' is block of code}
button is pressed(name)->bool
on button pressed(body)
acceleration(dimension)->number
compass heading()->number
calibrate()
running time()->number
on shake(body)
on fall(body)
on screen up(body)
on screen down(body)
on logo up(body)
on logo down(body)
*pin is pressed(name)->bool
*on pin pressed(body)
MICROBIT.IMAGE NAMESPACE
------------------------
create image
img->clear()
img->set pixel(x,y,value)
img->pixel(x,y)->bool
img->show image(x offset)
img->scroll image(x offset per step, interval)
img->width()->int
MICROBIT.PINS NAMESPACE
-----------------------
analog read pin(name)->number
analog write pin(name, value)
digital read pin(name)->number
digital write pin(name, value)
-pin is pressed [moved to input namespace]
-on pin pressed [moved to input namespace]
MICROBIT.MATH NAMESPACE
-----------------------
abs(x)->number
clamp(min, max, value)->number
max(x, y)->number
min(x, y)->number
mod(x, y)->number
pow(x, y)->number
random(limit)->number
*sqrt(x)->number
*sign(x)->number
MICROBIT.BITS NAMESPACE
-----------------------
add int32
multiply int32
subtract int32
and uint32(x, y)->number
xor uint32(x, y)->number
-not uint32 [removed]
-create buffer [removed]
-string to buffer [removed]
rotate left uint32(x, bits)->number
rotate right uint32(x, bits)->number
shift left uint32(x, bits)->number
shift right uint32(x, bits)->number
END.
___________________________________________________________
David Whale, B.Sc (Hons), MIET
*Software Engineer and IET Schools Liaison Officer, Essex*
email: dwhale at theiet.org
twitter: @whaleygeek
blog: blog.whaleygeek.co.uk
Co-author of the new book "Adventures in Minecraft" <http://amzn.to/ZGfxZG>
- lets get kids coding!
On 29 August 2015 at 12:51, David Whale <david at thinkingbinaries.com> wrote:
> Actually, I'll stand up and be counted. I'll do a first pass of this now
> as a "stake in the ground", which others than then attack with the flame
> thrower.
>
> Back in 20 mins.
>
> D
>
>
> ___________________________________________________________
> David Whale, B.Sc (Hons), MIET
> *Software Engineer and IET Schools Liaison Officer, Essex*
>
> email: dwhale at theiet.org
> twitter: @whaleygeek
> blog: blog.whaleygeek.co.uk
>
> Co-author of the new book "Adventures in Minecraft"
> <http://amzn.to/ZGfxZG> - lets get kids coding!
>
>
> On 29 August 2015 at 12:48, David Whale <david at thinkingbinaries.com>
> wrote:
>
>> Hi Nicholas,
>>
>> I do get what you are saying about it being their first Python
>> experience, and therefore it does make sense for that to be a good Python
>> experience, as well as a good micro:bit experience. Good point.
>>
>> I think the best first step is to propose the top end of the Python API
>> on this mailing list so we can see what it might look like, it will then be
>> easier to see where additional value or 'Pythonic' magic could be added to
>> make it easier and more natural in that language. However, I think the
>> first step is to list all the namespaces, methods, and parameters in one
>> list (I *think* this is just a matter of working through this page and
>> writing down the Python equivalent):
>>
>> https://live.microbit.co.uk/td/contents
>>
>> That's probably a 20 minute task for a first stab that makes no effort at
>> adding Pythonic beauty, and it then creates something that we could discuss
>> as a community and make sensible compromises in various places, as you say,
>> between consistency with the TD vocabulary and a specific Python enabled or
>> enhanced experience.
>>
>> I'm happy to write down that first list as a straw-man for others to
>> shoot down in flames, if you want.
>>
>> David
>>
>>
>> ___________________________________________________________
>> David Whale, B.Sc (Hons), MIET
>> *Software Engineer and IET Schools Liaison Officer, Essex*
>>
>> email: dwhale at theiet.org
>> twitter: @whaleygeek
>> blog: blog.whaleygeek.co.uk
>>
>> Co-author of the new book "Adventures in Minecraft"
>> <http://amzn.to/ZGfxZG> - lets get kids coding!
>>
>>
>> On 29 August 2015 at 12:19, Nicholas H.Tollervey <ntoll at ntoll.org> wrote:
>>
>>> Hi David,
>>>
>>> Many thanks for the comments.
>>>
>>> I've looked at the TouchDevelop API and - to be honest - I have
>>> significant problems with it. As a teacher I'm left wondering how an
>>> average (i.e. a SATs level 4) 11yo would react to such a complicated
>>> beast. As a developer, I'm concerned about some of the vague naming
>>> ("callibrate" - callibrate what?), apparent duplications (drawing pixels
>>> on the display) and size of it all when you think about the simplicity
>>> of the micro:bit device itself.
>>>
>>> I believe that if we base the Python API on this we're going to end up
>>> with a horrible mess.
>>>
>>> When we looked at TouchDevelop we (as in those of us in the Python
>>> community who had signed the NDA) came to the conclusion that it was
>>> such a different beast to Python, that we'd be fitting a square peg into
>>> a round hole. We decided that TD is obviously a wonderful resource, it's
>>> just it's not a very Pythonic resource and trying to make Python work
>>> with it would end up in some weird shonky compromise that created more
>>> problems than it solved.
>>>
>>> I also believe there's something to be said for providing alternatives.
>>>
>>> Given that both the TD and Python API will ultimately sit on top of the
>>> DAL they will, of course, be similar. However, the way the API is
>>> expressed will be different simply because TD and Python ARE different.
>>> Nevertheless, I suspect we will use the same names as the DAL (display,
>>> IO, button A etc) but will probably make them conform to the Python
>>> PEP-8 standard (so it'll be button_a for example).
>>>
>>> But most importantly, we need to build something appropriate for a
>>> reading age of 11.
>>>
>>> Our aim must be to build the *best* API we can for kids to learn about
>>> the micro:bit via Python. If it's inconsistent with Microsoft's then so
>>> be it. Viva la difference and let many flowers bloom! If we do our job
>>> right then kids shouldn't have a problem moving between platforms.
>>> Python's API ought to feel natural and fun to use from the perspective
>>> of an 11yo. This beats consistency every time.
>>>
>>> Of course, we'll be sharing what we're doing via this list. We need help
>>> from people on this list! Please feel free to jump in, offer
>>> constructive critique and ideas. This is potentially the way a million
>>> children first experience Python.
>>>
>>> It's important work!
>>>
>>> Best wishes,
>>>
>>> N.
>>>
>>> On 28/08/15 20:00, David Whale wrote:
>>> > Nicholas,
>>> >
>>> > I'd be interested in reviewing the API spec proposals when they are
>>> done
>>> > (naming and containership of namespaces, parameters etc).
>>> >
>>> > Just one point. I'd like to propose that there is significant value in
>>> > using *exactly* the same names as are already used in the TouchDevelop
>>> > API, with exactly the same groupings. There's been a lot of work
>>> > recently to consolidate the TouchDevelop, Blocks [and to some extent
>>> > CodeKingdoms] vocabulary for things, so that it is a mostly seamless
>>> > experience to move from one language to another, with the transferrable
>>> > knowledge of the common micro:bit API tying everything together.
>>> >
>>> > Please do look back at the TouchDevelop, there have been a number of
>>> > commits to the live site in the last week or two with changes to
>>> default
>>> > namespaces, some additional 'standard' linked in libraries like bits,
>>> > game, and events, some name changes, and stuff like that. system_time()
>>> > for example is not one of the vocabulary words in use in the live
>>> > system, it has been renamed a few times and has settled now on "running
>>> > time".
>>> >
>>> > I don't think we should get too hung up on it being "Pythonic", as long
>>> > as it is 'Python'.
>>> >
>>> > David
>>> >
>>> > ___________________________________________________________
>>> > David Whale, B.Sc (Hons), MIET
>>> > *Software Engineer and IET Schools Liaison Officer, Essex*
>>> >
>>> > email: dwhale at theiet.org <mailto:dwhale at theiet.org>
>>> > twitter: @whaleygeek
>>> > blog: blog.whaleygeek.co.uk <http://blog.whaleygeek.co.uk>
>>> >
>>> > Co-author of the new book "Adventures in Minecraft"
>>> > <http://amzn.to/ZGfxZG> - lets get kids coding!
>>> >
>>> >
>>> > On 28 August 2015 at 16:08, Nicholas H.Tollervey <ntoll at ntoll.org
>>> > <mailto:ntoll at ntoll.org>> wrote:
>>> >
>>> > Hi Folks,
>>> >
>>> > Although this list has been a tad quiet recently, things are moving
>>> > along when it comes to Python on the micro:bit.
>>> >
>>> > The "blessed" device abstraction layer (DAL) created by Lancaster
>>> > University for the BBC to use with the micro:bit is now working
>>> with
>>> > MicroPython.
>>> >
>>> > What we need to do is create a Pythonic "microbit" module that
>>> gives
>>> > users of Python direct access to the device hardware via the DAL.
>>> >
>>> > In terms of the work, this is simply a task of code-plumbing.
>>> However,
>>> > the challenge will be in creating something that is Pythonic and
>>> easy
>>> > enough for the nation's 11yo to get their heads around. That means
>>> > obvious mono-syllabic names and shallow namespaces while still
>>> retaining
>>> > the "shape" of the DAL.
>>> >
>>> > So, I'm going to start writing some documentation about the various
>>> > features that the DAL exposes and both Damien and I would like
>>> help in
>>> > designing the API (since actually coding it is a relatively simple
>>> task
>>> > of connecting Python to the DAL). It's definitely a case of more
>>> eyes
>>> > will make this better.
>>> >
>>> > In case you're wondering, we already have made a start. So for
>>> example,
>>> > here's the output from MicroPython's help() function:
>>> >
>>> > >>> help()
>>> > Welcome to MicroPython on the micro:bit!
>>> >
>>> > Be brave! Break things! Learn and have fun! :-)
>>> >
>>> > Type 'import microbit', press return and try these commands:
>>> > microbit.display.scroll('Hello')
>>> > microbit.system_time()
>>> > microbit.sleep(1000)
>>> > microbit.button_a.is_pressed()
>>> > What do these commands do? Can you improve them? HINT: use the up
>>> and
>>> > down arrow keys to get your command history (saves you typing).
>>> >
>>> > Explore:
>>> > Type 'help(something)' to find out about it. Type 'dir(something)'
>>> to
>>> > see what it can do.
>>> >
>>> > Stuff to explore:
>>> > microbit.accelerometer -- detect the device's position
>>> > (orientation)
>>> > microbit.button_a.is_pressed() -- is button A pressed? (True or
>>> False)
>>> > microbit.button_b.is_pressed() -- is button B pressed? (True or
>>> False)
>>> > microbit.compass -- detect the device's heading
>>> > microbit.display -- display things (pixels,
>>> characters,
>>> > words)
>>> > microbit.panic() -- go into panic mode (requires a
>>> > restart)
>>> > microbit.random(n) -- get a random number between 0
>>> and n
>>> > microbit.sleep(n) -- wait for n milliseconds (1
>>> second =
>>> > 1000)
>>> > microbit.system_time() -- get the number of milliseconds
>>> since
>>> > reset
>>> >
>>> > Control commands:
>>> > CTRL-C -- stop a running program
>>> > CTRL-D -- on a blank line, do a soft reset of the
>>> micro:bit
>>> >
>>> >
>>> > The only major part of the DAL we've not already started to
>>> reference is
>>> > the IO namespace for accessing the pins along the bottom of the
>>> device.
>>> >
>>> > Pretty much all of the above namespaces have things missing or
>>> clunkily
>>> > named.
>>> >
>>> > So, fancy helping 1 million kids learn and play with Python? You
>>> will be
>>> > given credit in the code and perhaps an easter egg I have in mind.
>>> ;-)
>>> >
>>> > Let me know your thoughts!
>>> >
>>> > Best wishes,
>>> >
>>> > Nicholas.
>>> >
>>> >
>>> > _______________________________________________
>>> > Microbit mailing list
>>> > Microbit at python.org <mailto:Microbit at python.org>
>>> > https://mail.python.org/mailman/listinfo/microbit
>>> >
>>> >
>>> >
>>> >
>>> > _______________________________________________
>>> > Microbit mailing list
>>> > Microbit at python.org
>>> > https://mail.python.org/mailman/listinfo/microbit
>>> >
>>>
>>>
>>>
>>> _______________________________________________
>>> Microbit mailing list
>>> Microbit at python.org
>>> https://mail.python.org/mailman/listinfo/microbit
>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/mailman/private/microbit/attachments/20150829/454048e0/attachment-0001.html>
More information about the Microbit
mailing list