Skip to content

Commit 56588d6

Browse files
thomasjballthomasjball
authored
Merge pull request #102 from microbit-apps/newDocs
start plan
2 parents c15a32c + caaad34 commit 56588d6

4 files changed

Lines changed: 236 additions & 3 deletions

File tree

‎assets/strings/en/tooltips.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@
122122
"T157": "3",
123123
"T158": "4",
124124
"T159": "5",
125-
"T160": "LED image",
125+
"T160": "image",
126126
"T161": "red",
127127
"T162": "purple",
128128
"T163": "giggle",

‎docs/doc-plan.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# The MicroCode Language
2+
3+
This document presents a detailed accounting of the syntax and
4+
semantics of the MicroCode language. Its intended audience are
5+
those who are familiar with programming languages and would like
6+
to understand the MicroCode language in depth. We also will
7+
use it as the basis for generating friendlier descriptions
8+
that use MicroCode's visual presentation, as well as to
9+
generate tests and aid in the translation of MakeCode programs
10+
to MicroCode programs,
11+
12+
## Syntax
13+
14+
MicroCode has a concrete syntax, as detailed below, for the
15+
purpose of creating programs without the need for visual
16+
MicroCode editor.
17+
18+
In the following, a word in ALLCAPS refers to a non-terminal in
19+
MicroCode's grammar. All other words are terminal symbols, with
20+
the following exceptions: <float> is a floating point number;
21+
<pos> is an integer greater than zero; // designates a comment
22+
(just for use in this markdown - MicroCode does not support comments);
23+
the symbols \s, \*, (, ), [, ], and | are part of the grammar
24+
specification. Words are always separated by whitespace.
25+
26+
Note that non-terminals correspond to the tooltips used in MicroCode's
27+
visual editor (where the underscores are replaced by spaces), which
28+
accounts for their long form.
29+
30+
A program (PROG) consists of 5 pages, numbered 1-5, each with a (possibly
31+
empty) sequence of rules RULE:
32+
33+
PROG := page_1 RULE\* page_2 RULE\* page_3 RULE\* page_4 RULE\* page_5 RULE\*
34+
35+
So, the following program is the empty program
36+
37+
```
38+
page_1 page_2 page_3 page_4 page_5
39+
```
40+
41+
Each rule has an optional section WHEN and an optional section DO.
42+
43+
RULE := when [WHEN] do [DO]
44+
45+
The WHEN section specifies a signal of interest and, optionally, a filter on that signal.
46+
The DO section specifies an action and, optionally, parameters to that action.
47+
48+
WHEN :=
49+
| page_start [TS] // fires (once) when control transitions to this page, with optional delay
50+
| timer [TS] // set a timer to fire after a delay, execute repeatedly
51+
| press [PK] // fire on press of specified button PK
52+
| release [PK] // fire on release of specified button PK
53+
| move [MK] // fire on specified accelerometer event MK
54+
| sound [loud | quiet | C] // fire on loud/quiet event or comparison C of current sound level (0-255)
55+
| temperature [UD | C] // fire on UD event or comparison C of current temperature (in Celsius)
56+
| light [UD | C] // fire on UD event or comparison C of current light level (0-255)
57+
| magnet [UD | C] // fire on UD event or comparison C of current magnetic level
58+
| radio_receive [C] // fire when number arrives via radio, subject to optional comparison C
59+
| variable_X_set [C] // fire after variable X has been assigned, subject to optional comparison C
60+
| variable_Y_set [C] // fire after variable Y has been assigned, subject to optional comparison C
61+
| variable_Z_set [C] // fire after variable Z has been assigned, subject to optional comparison C
62+
63+
UD := up | down
64+
TS := (1/4_second | 1_second | 1_random_second | 5_seconds)\* // sum the sequence of times
65+
PK := button_A | button_B | logo | touch_pin_0 | touch_pin_1 | touch_pin_2
66+
MK := shake | tilt_left | tilt_right | tilt_up | tilt_down | face_down | face_up
67+
68+
Sensors and variables may be compared to values using C; sensors may also have events
69+
70+
C := CO E
71+
72+
Comparison operators CO are as follows:
73+
74+
CO :=
75+
| equals
76+
| not_equals
77+
| less_then
78+
| less_then_or_equal
79+
| greater_than
80+
| greater_than_or_equal
81+
82+
An expression E is either atomic A, a binary expression, or a randomly chosen value:
83+
84+
E :=
85+
| A
86+
| A + E
87+
| A / E
88+
| A - E
89+
| A * E
90+
| random_number PE
91+
92+
An atomic value A is either a floating point number, one of the three variables,
93+
or the current value of one of the four sensors, or the last value received over radio:
94+
95+
A :=
96+
| <float>
97+
| variable_X | variable_Y | variable_Z
98+
| light_value | sound_value | temp_value | magnet_value
99+
| radio_value
100+
101+
A positive (integer) expression PE is
102+
103+
PE :=
104+
| <pos>
105+
| <pos> + PE
106+
| <pos> * PE
107+
108+
A DO action
109+
110+
DO :=
111+
| show_number [V]
112+
| show_image (IMAGE)\* [repeat [PE]]
113+
| play_sound (SND)\* [repeat [PE]]
114+
| music (NOTES)* [repeat [PE]]
115+
| radio_send [V]
116+
| radio_set_group [PE]
117+
| set_variable_X [V]
118+
| set_variable_Y [V]
119+
| set_variable_Z [V]
120+
| switch_page [PAGE]
121+
122+
PAGE := | page_1 | page_2 | page_3 | page_4 | page_5
123+
SND := | giggle | happy | hello | mysterious | sad | slide | soaring
124+
125+
An led image occurs inside backquotes ` and consists of 25 characters, either . or 1, separated by
126+
whitespace:
127+
128+
IMAGE := image ` (.\s+ | 1\s+)25 `
129+
130+
A melody fragment consists of a sequence of 4 characters from the set { C, D, E, F, G, -},
131+
where - denotes a rest, inside backquotes:
132+
133+
NOTES := melody ` (C | D | E | F | G | -)4 `
134+
135+
## Semantics
136+
137+
Before execution starts, all variables (X, Y, and Z) are initialized to 0
138+
and the current value of all micro:bit/jacdac sensors is cached.
139+
The initial value of radio_value is undefined.
140+
The radio group is initialized to 1.
141+
Execution begins by transitioning to page 1.
142+
143+
### Defaults
144+
145+
The absence of an optional element/value results in the use of a default element/value, as follows:
146+
147+
- A rule with an empty do section never executes (no matching performed
148+
on it).
149+
- A rule with an empty when section defaults to page_start signal with no delay.
150+
- Signal defaults are as follows
151+
- page_start defaults to no delay
152+
- timer defaults to 1 second delay
153+
- press defaults to wildcard (any element in PK)
154+
- release defaults to wildcard (any element in PK)
155+
- move defaults to shake event
156+
- sound defaults to loud event
157+
- temperature, light, and magnet default to up event
158+
- radio and variable signals have no default, they fire even without a default
159+
- Action defaults are as follows
160+
- show_number defaults to 0
161+
- show_image defaults to smiley face
162+
- play_sound defaults to giggle
163+
- music defaults to `C E G C`
164+
- radio_send defaults to 0
165+
- radio_set_group defaults to 1
166+
- variable_X_set, variable_Y_set, variable_Z_set defaults to 0
167+
- switch_page with no page specified is a NOOP
168+
169+
### Signals
170+
171+
Execution of rules on the current page is driven by the reception
172+
of _signals_, which may come from the external environment (for
173+
example, when the user presses a button, shakes the micro:bit,
174+
or a sensor provides a new value) or may be generated by the
175+
MicroCode program itself (for example, by assigning to a variable
176+
or switching to another page).
177+
178+
Regardless of their origin, signals are ordered and processed one
179+
at a time using a FIFO queue. Each signal has a name corresponding to
180+
the signals named in the when section; a signal carries a payload, which
181+
may be an event or a value. Some special kinds of signals are
182+
used for timers, as detailed later.
183+
184+
### Resources and conflicts
185+
186+
Actions have effects through writing to resources, which are as follows:
187+
188+
- screen
189+
- speaker
190+
- radio group
191+
- radio channel
192+
- variable X
193+
- variable Y
194+
- variable Z
195+
- current page
196+
197+
If two rules have actions that target the same resource, they are said
198+
to be in _conflict_ if it is possible for them to execute at the same time.
199+
200+
### Rule matching
201+
202+
Upon reception of a signal, it is first necessary to find the
203+
rules that are enabled for execution by the signal. The first
204+
step is to find the rules that mention the named signal. Then
205+
the optional conditions associated with those rules are evaluated
206+
in the current state (of variable and sensor values) to prune this
207+
set to get the enabled set E. Finally, if two rules in E are in conflict
208+
then the rule that comes later in sequence is removed from E.
209+
210+
Once we have the final set E of enabled rules, we halt
211+
execution of any currently active rules that conflict with
212+
a rule in E.
213+
214+
The set E is then partition into three sets, I, S, and T, corresponding
215+
to rules whose actions execute instantly, those that switch page, and those that take time. Instant actions are
216+
217+
- assignments to variables
218+
- radio send
219+
- radio set group
220+
221+
The remaining actions (other than switch page) are the ones that (may) take time.
222+
223+
The actions in I are executed first and run to completion.
224+
Then, if S is not empty then
225+
it must be a singleton, so a page switch will take place, in which
226+
case actions in T are ignored. Else, if S is empty then actions in
227+
T are started.
228+
229+
### Updating state
230+
231+
### Switching pages
232+
233+
### Timers

‎locales/tooltips.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@
137137
"T158": "4",
138138
"T159": "5",
139139

140-
"T160": "LED image",
140+
"T160": "image",
141141
"T161": "red",
142142
"T162": "purple",
143143
"T163": "giggle",

‎tooltips.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ namespace microcode {
114114
else if (id === "T157") res = "3";
115115
else if (id === "T158") res = "4";
116116
else if (id === "T159") res = "5";
117-
else if (id === "T160") res = "LED image";
117+
else if (id === "T160") res = "image";
118118
else if (id === "T161") res = "red";
119119
else if (id === "T162") res = "purple";
120120
else if (id === "T163") res = "giggle";

0 commit comments

Comments
 (0)