Skip to content

Commit 682096d

Browse files
microbit-carlosmicrobit-carlos
committed
docs: Update README with up-to-date info and separate import docs.
1 parent 83d28e9 commit 682096d

File tree

3 files changed

+68
-99
lines changed

3 files changed

+68
-99
lines changed

‎README.rst

Lines changed: 42 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ BBC micro:bit MicroPython Editor for Browsers
33

44
|Build status|
55

6-
This project is an editor that targets the MicroPython
7-
(http://micropython.org) version of the Python programming language
8-
(http://python.org/). Code written with this editor is expected to run on the
9-
BBC's micro:bit device (https://en.wikipedia.org/wiki/Micro_Bit).
6+
This project is an editor that targets the `MicroPython
7+
<https://micropython.org>`_ version of the `Python programming language
8+
<http://python.org/>`_. Code written with this editor is expected to run on the
9+
`BBC micro:bit device <https://microbit.org>`_.
1010

1111
Developer Setup
1212
---------------
@@ -20,32 +20,32 @@ submodules::
2020
cd PythonEditor
2121
git submodule update --init --recursive
2222

23-
**THIS NEEDS TO BE DONE BEFORE ANYTHING ELSE, OR IT WILL NOT WORK.**
24-
2523
Assuming you have Python 3 installed you can serve the editor like this::
2624

2725
$ ./bin/show
2826
http://localhost:8000/editor.html
2927
Serving HTTP on 0.0.0.0 port 8000 ...
3028

31-
As the script tells us, point your browser to http://localhost:8000/editor.html.
29+
You can also look at the script content and execute the same, or similar,
30+
command on a terminal as long as it serves the contents of this repository on
31+
port `8000`. `This article <https://gist.github.com/willurd/5720255>`_ shows
32+
other ways to achieve the same.
33+
34+
Then, point your browser to http://localhost:8000/editor.html.
3235

33-
It's also possible to run the editor directly from the file system like this,
34-
for example::
36+
Tests
37+
+++++
3538

36-
$ firefox editor.html
39+
There are two ways to run tests:
3740

38-
Or by double-clicking on the ``editor.html`` file from your file manager.
41+
* A portion of the tests can be run in the browser
3942

40-
**IMPORTANT**: When the editor is run from the file system, the "sharing"
41-
button is hidden. Because of security reasons, many local browsers won't allow
42-
it to function correctly unless the editor is properly served from a network
43-
domain rather than directly from the file system.
43+
- Serve the editor and point your browser to
44+
``http://localhost:8000/tests.html``.
4445

45-
Tests
46-
+++++
46+
* The full test suit can be run with Node.js
4747

48-
Simply point your browser to the ``tests.html`` file.
48+
- ``cd tests && npm install && npm run test``
4949

5050
Tests are in the ``tests`` directory with their own README explaining how they
5151
work.
@@ -54,19 +54,23 @@ Code
5454
++++
5555

5656
* ace - a directory containing the Ace editor (http://ace.c9.io).
57+
* bin - a directory containing useful scripts.
5758
* blockly - a GIT sub-module containing Google's blockly project.
59+
* docs - a directory containing more documentation for the editor.
60+
* js - a directory containing the JavaScript code for running the editor.
5861
* CHANGELOG - a record of how things have changed between versions.
5962
* CONTRIBUTING.rst - a guide for people who want to contribute (you should!).
6063
* editor.html - the page to be loaded by your browser.
61-
* firmware.hex - copy of the "vanilla" MicroPython firmware used by the editor.
6264
* help.html - a single page user facing help page.
65+
* lang - a directory containing the editor translations.
6366
* LICENSE - a copy of the MIT software license that covers this code.
6467
* microbit_blocks - a GIT sub-module containing custom MicroPython blocks.
68+
* micropython - a directory with the MicroPython hex files used by the editor.
6569
* python-main.js - the JavaScript code for running the editor.
6670
* README.rst - this file, the clue is in the name. ;-)
6771
* tests.html - the browser based test runner.
68-
* show.sh - a script that allows you to serve the editor from localhost. Requires Python 3.
69-
* static - contains css, js and img sub-directories.
72+
* show.sh - a script that allows you to serve the editor from localhost.
73+
* static - contains third party css, js and img sub-directories.
7074
* tests - contains the Python specific test suite.
7175
* tests.html - point your browser at this file to run the tests.
7276

@@ -86,80 +90,20 @@ auto-indentation.
8690

8791
All new scripts default to something simple and sensible.
8892

89-
The default name for a new script is ``microbit``. The default comment is
90-
``A MicroPython script``. The default code is a short program to repeatedly
91-
display ``Hello, World!`` followed by a heart. You can change these at any time
92-
by clicking on them.
93+
The default name for a new script is ``microbit``. The default code is a
94+
short program to repeatedly display ``Hello, World!`` followed by a heart.
95+
You can change these at any time by clicking on them.
9396

94-
It is possible to override the default name, comment and code via query string
95-
arguments in the URL. For example, appending ``?name=My%20script`` to the
96-
editor's URL will update the name of the script. Furthermore, appending
97-
``?name=My%20script&comment=A%20different%20comment`` will override both the
98-
name and comment. Please note that all query string arguments must be correctly
99-
URL encoded - this especially applies to code. Use the "share" button in the
100-
editor to generate and share such URLs with appended query strings.
101-
102-
The layout and functionality is deliberately simple. The buttons at the
103-
top left, act as follows:
104-
105-
* Download - creates a .hex file locally in the user's browser and prompts the user to download it. The resulting file should be copied over to the micro:bit device just like when using all the other editors. The filename will be the name of the script with spaces replaced by "_" and ending in .hex. So "extraordinary script" is saved as extraordinary_script.hex.
106-
* Save - download a copy of the Python source code. The filename will be the name of the script with spaces replaced by "_" and ending in .py.
107-
* Blockly - arrange visual blocks to quickly create Python code. Moving such blocks will re-write your Python code and you may lose work. Furthermore, the arrangement of blocks is currently not saved, just the resulting Python code as described above.
108-
* Snippets - allow user's to write code from pre-defined Python fragments (functions, loops, if...else etc). They are triggered by typing a keyword followed by TAB. For example, type "wh" followed by TAB to insert a while... loop. Clicking on the code snippets button opens up a modal dialog window containing instructions and a table of the available snippets along with their trigger and a short and simple description.
109-
* Help - opens a single page in a new tab that contains user-facing help.
110-
* Share - generate a short URL for the script. Share this with others. This button will be missing if run from the local file system.
111-
112-
Directly next to the large buttons are two smaller icons. The zoom in and
113-
zoom out buttons that make it easy for teachers to display code via a projector.
97+
The layout and functionality is deliberately simple. A description of the
98+
buttons can be found in the [help page](help.html).
11499

115100
If you have a Python script or hex file on your local computer, you can load it
116101
into the editor by dragging it onto the text area.
117102

118-
If you plug in your micro:bit and want to get the REPL you'll need to install
119-
pyserial and run the following command with the appropriate permissions (such
120-
as root, as shockingly demonstrated below)::
121-
122-
$ sudo python -m serial.tools.miniterm -b 115200 /dev/ttyACM0
123-
124-
Remember to replace ``/dev/ttyACM0`` with the appropriate device for your computer.
125-
126-
The .hex file is generated in the following way:
127-
128-
* A "vanilla" version of the MicroPython hex is hidden within the DOM.
129-
* We take the Python code in the editor and turn it into a hex representation.
130-
* We insert the Python derived hex into the correct place within the MicroPython hex.
131-
* The resulting combination is downloaded onto the user's local filesystem for flashing onto the device.
132-
133-
The hidden MicroPython hex is just over 600k. While this sounds large, it's
134-
relatively small when you consider:
135-
136-
* The Guardian's front page is around 1.5mb
137-
* Compression is built into the server
138-
* The web has caching built in (we should trust it)
139-
* We actually want kids to view source and find the .hex file in as raw a form as possible.
140-
141-
Importing Projects
142-
++++++++++++++++++
143-
Python projects from external sources can be imported into the editor using a special URL e.g.
144-
``https://python.microbit.org/v/1.1#project:{{ encoded project }}``
145-
146-
To encode a project, it must be structured as follows:
147-
148-
::
149-
150-
{
151-
meta: {
152-
cloudId: "microbit.co.uk", # optional
153-
comment: "A MicroPython script", # required - may be blank
154-
editor: "python", # required - editor name
155-
lastUse: 1538407830, # optional - UNIX time the script was last used
156-
name: "unearthly script 2" # required - may be blank
157-
},
158-
source: "# Add your Python code here. E.g.\r\n from microbit import *\r\n while True:\r\n display.scroll('Hello, World!')\r\nsleep(2000)"
159-
}
160-
161-
This JSON structure is compressed using `LZMA
162-
<https://github.com/LZMA-JS/LZMA-JS>`_, and then encoded as Base64 to include in the import URL.
103+
The micro:bit can then be programmed by downloading a hex file into your
104+
computer and then copying the file into the MICROBIT drive. If you are using
105+
a Chrome-based browser you also have the option to connect via WebUSB and
106+
flash the micro:bit directly from the browser.
163107

164108
Configuration
165109
-------------
@@ -171,17 +115,18 @@ containing translation strings and feature flags. Take a look in the
171115
Documentation
172116
-------------
173117

174-
For documentation for this project - you're reading it. ;-)
118+
More documentation can be found in the `docs folder <docs>`_.
175119

176-
For in-editor documentation aimed at the user, this is in the help.html file.
120+
For in-editor documentation aimed at the user, this is in the `help.html file
121+
<help.html>`_.
177122

178123
Metrics
179-
-------------
124+
-------
180125

181-
In order to help developers measure the way features of the editor are being used,
182-
all buttons and actions have an 'action' class added to them. Measurement can then
183-
be added by anyone deploying the editor through inclusion of a script that attaches
184-
events to these actions and counts them.
126+
In order to help developers measure the way features of the editor are being
127+
used, all buttons and actions have an 'action' class added to them. Measurement
128+
can then be added by anyone deploying the editor through inclusion of a script
129+
that attaches events to these actions and counts them.
185130

186131
Legacy
187132
------

‎docs/README.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Developer docs
22

3+
- [Embed the Editor](embedEditor.md)
34
- [Filesystem](filesystem.md)
5+
- [Import Projects](import.md)
6+
- [Release Checklist](release_todo.md)
47
- [Translation Strategy](translations.md)
5-
- [Embed editor](embedEditor.md)
6-
- [Release TODO](release_todo.md)

‎docs/import.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Import Projects into the Python Editor
2+
3+
Python projects from external sources can be imported into the editor using a special URL e.g.
4+
``https://python.microbit.org/v/1.1#project:{{ encoded project }}``
5+
6+
To encode a project, it must be structured as follows:
7+
8+
```json
9+
{
10+
meta: {
11+
cloudId: "microbit.co.uk", # optional
12+
comment: "A MicroPython script", # required - may be blank
13+
editor: "python", # required - editor name
14+
lastUse: 1538407830, # optional - UNIX time the script was last used
15+
name: "unearthly script 2" # required - may be blank
16+
},
17+
source: "# Add your Python code here. E.g.\r\n from microbit import *\r\n while True:\r\n display.scroll('Hello, World!')\r\nsleep(2000)"
18+
}
19+
```
20+
21+
This JSON structure is compressed using
22+
[LZMA](https://github.com/LZMA-JS/LZMA-JS), and then encoded as Base64 to
23+
include in the import URL.

0 commit comments

Comments
 (0)