From e23938af182f18d27dee4107b2b3dfb94b6d9d50 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Thu, 20 Nov 2025 11:49:46 -0800 Subject: [PATCH 1/9] start plan --- docs/doc-plan.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/doc-plan.md diff --git a/docs/doc-plan.md b/docs/doc-plan.md new file mode 100644 index 00000000..e69de29b From 0ed3d447db3dd350523e6b38e939a447fb17bf75 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Fri, 28 Nov 2025 23:31:03 -0800 Subject: [PATCH 2/9] work on syntax --- docs/doc-plan.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index e69de29b..8b887fdf 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -0,0 +1,37 @@ +MicroCode programs consist of 5 pages, numbered 1 - 5. +Execution always starts on page 1. Before execution +starts, all variables are initialized to 0 and the current value of all sensors is cached. + +A page consists of a sequence of rules, ordered from top to bottom. +Each rule has a When section and a Do section. +The When section specifies an event of interest +and, optionally, a filter on that event. + +When + +page-start [timespan] +timer [timespan] +press [pressable-kind] +release [pressable-kind] +move [move-kind] +sound [loud-quiet,compare] +temperature [up-down,compare] +light [up-down,compare] +magnet [up-down,compare] +radio-receive [compare] +variable-X-set [compare] +variable-Y-set [compare] +variable-Z-set [compare] + +Do + +show-number [value] +show-image [image*] [repeat [pos-value]] +play-sound [sound*] [repeat [pos-value]] +play-music [notes*] [repeat [pos-value]] +radio-send [value] +radio-set-group [pos-value] +set-variable-X [value] +set-variable-Y [value] +set-variable-Z [value] +switch-page [page] From 8b0e727fb92d4daaea9c3138a24841eca25c40ad Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Sat, 29 Nov 2025 09:45:32 -0800 Subject: [PATCH 3/9] grammar --- docs/doc-plan.md | 75 +++++++++++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 29 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 8b887fdf..c5e9708d 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -1,37 +1,54 @@ MicroCode programs consist of 5 pages, numbered 1 - 5. Execution always starts on page 1. Before execution -starts, all variables are initialized to 0 and the current value of all sensors is cached. +starts, all variables are initialized to 0 and +the current value of all sensors is cached. -A page consists of a sequence of rules, ordered from top to bottom. -Each rule has a When section and a Do section. -The When section specifies an event of interest +A page consists of a sequence of rules (R), ordered from top to bottom. +Each rule has an option when section W and an optional do section D. +The when section specifies an event of interest and, optionally, a filter on that event. +The do section specifies an action and, optionally, +parameters to that action. +Some actions can be repeated. -When +R := [W] [D] -page-start [timespan] -timer [timespan] -press [pressable-kind] -release [pressable-kind] -move [move-kind] -sound [loud-quiet,compare] -temperature [up-down,compare] -light [up-down,compare] -magnet [up-down,compare] -radio-receive [compare] -variable-X-set [compare] -variable-Y-set [compare] -variable-Z-set [compare] +W := +| page-start [TS] +| timer [TS] +| press [PK] +| release [PK] +| move [MK] +| sound [loud | quiet | C] +| temperature [up | down | C] +| light [up | down | C] +| magnet [up | down | C] +| radio-receive [C] +| variable-X-set [C] +| variable-Y-set [C] +| variable-Z-set [C] -Do +TS := (1/4-second | 1-second | 1-random-second | 5-seconds)\* +PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 +MK := shake | tilt-left | tilt-right | ... +C := CO V -show-number [value] -show-image [image*] [repeat [pos-value]] -play-sound [sound*] [repeat [pos-value]] -play-music [notes*] [repeat [pos-value]] -radio-send [value] -radio-set-group [pos-value] -set-variable-X [value] -set-variable-Y [value] -set-variable-Z [value] -switch-page [page] +D := +| show-number [V] +| show-image (image)_ [repeat [PV]] +| play-sound (sound)_ [repeat [PV]] +| play-music (notes)\* [repeat [PV]] +| radio-send [V] +| radio-set-group [PV] +| set-variable-X [V] +| set-variable-Y [V] +| set-variable-Z [V] +| switch-page [PG] + +CO := +| equals +| not-equals +| less-then +| less-then-or-equal +| greater-than +| greater-than-or-equal From d473b50dbcbcd9047437e65af4dfb5deaa944643 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Sat, 29 Nov 2025 10:54:56 -0800 Subject: [PATCH 4/9] more grammar --- docs/doc-plan.md | 53 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index c5e9708d..11b8159e 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -3,16 +3,20 @@ Execution always starts on page 1. Before execution starts, all variables are initialized to 0 and the current value of all sensors is cached. -A page consists of a sequence of rules (R), ordered from top to bottom. +A page consists of a sequence of rules (R): + +P := page-D R\* + Each rule has an option when section W and an optional do section D. + +R := when [W] do [D] + The when section specifies an event of interest and, optionally, a filter on that event. The do section specifies an action and, optionally, parameters to that action. Some actions can be repeated. -R := [W] [D] - W := | page-start [TS] | timer [TS] @@ -20,19 +24,48 @@ W := | release [PK] | move [MK] | sound [loud | quiet | C] -| temperature [up | down | C] -| light [up | down | C] -| magnet [up | down | C] +| temperature [UD | C] +| light [UD | C] +| magnet [UD | C] | radio-receive [C] | variable-X-set [C] | variable-Y-set [C] | variable-Z-set [C] +UD := up | down TS := (1/4-second | 1-second | 1-random-second | 5-seconds)\* PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 MK := shake | tilt-left | tilt-right | ... + C := CO V +CO := +| equals +| not-equals +| less-then +| less-then-or-equal +| greater-than +| greater-than-or-equal + +V := +| A +| A + V +| A / V +| A - V +| A \* V +| random PV + +A := +| +| var-X | var-Y | var-Z +| light-value | sound-value | temp-value | magnet-value +| radio-value + +PV := +| int>0 +| int>0 + PV +| int>0 \* PV + D := | show-number [V] | show-image (image)_ [repeat [PV]] @@ -45,10 +78,4 @@ D := | set-variable-Z [V] | switch-page [PG] -CO := -| equals -| not-equals -| less-then -| less-then-or-equal -| greater-than -| greater-than-or-equal +PG := | page-1 | page-2 | page-3 | page-4 | page-5 \ No newline at end of file From e9298f3658b8fb7c2ede01ca0d3eb7b7a21637f9 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Fri, 26 Dec 2025 15:30:46 -0700 Subject: [PATCH 5/9] work on syntax --- docs/doc-plan.md | 154 ++++++++++++++++++++++++++--------------------- 1 file changed, 87 insertions(+), 67 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 11b8159e..834f5148 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -1,81 +1,101 @@ -MicroCode programs consist of 5 pages, numbered 1 - 5. -Execution always starts on page 1. Before execution -starts, all variables are initialized to 0 and -the current value of all sensors is cached. +# The MicroCode Language -A page consists of a sequence of rules (R): +## Syntax -P := page-D R\* +In the following, a word in ALLCAPS refers to a non-terminal in +MicroCode's grammar. Words in lowercase are terminal symbols and +may have dashes and other symbols in them. is a floating +point number; is an integer greater than zero. Comments follow //. -Each rule has an option when section W and an optional do section D. +A program (PROG) consists of 5 pages, number 1-5, each with a possibly empty sequence of +rules RULE: -R := when [W] do [D] + PROG := page-1 RULE\* page-2 RULE\* page-3 RULE\* page-4 RULE\* page-5 RULE\* -The when section specifies an event of interest -and, optionally, a filter on that event. -The do section specifies an action and, optionally, -parameters to that action. +Each rule has an option when section WHEN and an optional do section DO. + + RULE := when [WHEN] do [DO] + +The WHEN section specifies an event of interest and, optionally, a filter on that event. +The DO section specifies an action and, optionally, parameters to that action. Some actions can be repeated. -W := -| page-start [TS] -| timer [TS] -| press [PK] -| release [PK] -| move [MK] -| sound [loud | quiet | C] -| temperature [UD | C] -| light [UD | C] -| magnet [UD | C] -| radio-receive [C] -| variable-X-set [C] -| variable-Y-set [C] -| variable-Z-set [C] - -UD := up | down -TS := (1/4-second | 1-second | 1-random-second | 5-seconds)\* -PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 -MK := shake | tilt-left | tilt-right | ... - -C := CO V - -CO := -| equals -| not-equals -| less-then -| less-then-or-equal -| greater-than -| greater-than-or-equal - -V := -| A -| A + V -| A / V -| A - V -| A \* V -| random PV - -A := -| -| var-X | var-Y | var-Z -| light-value | sound-value | temp-value | magnet-value -| radio-value - -PV := -| int>0 -| int>0 + PV -| int>0 \* PV - -D := + WHEN := + | page-start [TS] // fires (once) when control transitions to this page, with optional delay + | timer [TS] // set a timer to fire after a delay, execute repeatedly after associated action completes + | press [PK] // fire on press of specified button PK + | release [PK] // fire on release of specified button PK + | move [MK] // fire on specified accelerometer event MK + | sound [loud | quiet | C] // fire on loud/quiet event or comparison C of current sound level (0-255) + | temperature [UD | C] // fire on UD event or comparison C of current temperature (in Celcius) + | light [UD | C] // fire on UD event or comparison C of current light level (0-255) + | magnet [UD | C] // fire on UD event or comparison C of current magnetic level + | radio-receive [C] // fire when number arrives via radio, subject to optional comparison C + | variable-X-set [C] // fire after variable X has been assigned, subject to optional comparison C + | variable-Y-set [C] // fire after variable Y has been assigned, subject to optional comparison C + | variable-Z-set [C] // fire after variable Z has been assigned, subject to optional comparison C + + UD := up | down + TS := (1/4-second | 1-second | 1-random-second | 5-seconds)\* // sum the sequence of times + PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 + MK := shake | tilt-left | tilt-right | ... + +Sensors and variables may be compared to values using C; sensors may also have events + + C := CO E + +Comparison operators CO are as follows: + + CO := + | equals + | not-equals + | less-then + | less-then-or-equal + | greater-than + | greater-than-or-equal + +An expression E is either atomic A, a binary expression, or a randomly chosen value: + + E := + | A + | A + E + | A / E + | A - E + | A * E + | random PE + +An atomic value A is either a floating point number, one of the three variables, +or the current value of one of the four sensors, or the last value received over radio: + + A := + | + | var-X | var-Y | var-Z + | light-value | sound-value | temp-value | magnet-value + | radio-value + +A positive (integer) expression PE is + + PE := + | + | + PE + | * PE + +DO := | show-number [V] -| show-image (image)_ [repeat [PV]] -| play-sound (sound)_ [repeat [PV]] -| play-music (notes)\* [repeat [PV]] +| show-image (image)_ [repeat [PE]] +| play-sound (sound)_ [repeat [PE]] +| play-music (notes)\* [repeat [PE]] | radio-send [V] -| radio-set-group [PV] +| radio-set-group [PE] | set-variable-X [V] | set-variable-Y [V] | set-variable-Z [V] | switch-page [PG] -PG := | page-1 | page-2 | page-3 | page-4 | page-5 \ No newline at end of file +PG := | page-1 | page-2 | page-3 | page-4 | page-5 + +## Semantics + +Before execution starts, all variables are initialized to 0 and +the current value of all micro:bit/jacdac sensors is cached. +Execution begins by transitioning to page 1. From 5bbf68a7e43a96b0445ebe2a1de638d20092fccf Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Fri, 26 Dec 2025 19:29:48 -0700 Subject: [PATCH 6/9] more on syntax --- docs/doc-plan.md | 48 ++++++++++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 834f5148..289d7c42 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -3,14 +3,15 @@ ## Syntax In the following, a word in ALLCAPS refers to a non-terminal in -MicroCode's grammar. Words in lowercase are terminal symbols and -may have dashes and other symbols in them. is a floating -point number; is an integer greater than zero. Comments follow //. +MicroCode's grammar. All other words are terminal symbols and +may have dashes and other symbols in them, with the following +exceptions: is a floating point number; is an +integer greater than zero; // designates a comment. A program (PROG) consists of 5 pages, number 1-5, each with a possibly empty sequence of rules RULE: - PROG := page-1 RULE\* page-2 RULE\* page-3 RULE\* page-4 RULE\* page-5 RULE\* + PROG := page-1 RULE* page-2 RULE* page-3 RULE* page-4 RULE* page-5 RULE* Each rule has an option when section WHEN and an optional do section DO. @@ -36,7 +37,7 @@ Some actions can be repeated. | variable-Z-set [C] // fire after variable Z has been assigned, subject to optional comparison C UD := up | down - TS := (1/4-second | 1-second | 1-random-second | 5-seconds)\* // sum the sequence of times + TS := (1/4-second | 1-second | 1-random-second | 5-seconds)* // sum the sequence of times PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 MK := shake | tilt-left | tilt-right | ... @@ -80,19 +81,30 @@ A positive (integer) expression PE is | + PE | * PE -DO := -| show-number [V] -| show-image (image)_ [repeat [PE]] -| play-sound (sound)_ [repeat [PE]] -| play-music (notes)\* [repeat [PE]] -| radio-send [V] -| radio-set-group [PE] -| set-variable-X [V] -| set-variable-Y [V] -| set-variable-Z [V] -| switch-page [PG] - -PG := | page-1 | page-2 | page-3 | page-4 | page-5 +A DO action + + DO := + | show-number [V] + | show-image (IMAGE)* [repeat [PE]] + | play-sound (SND)* [repeat [PE]] + | play-music (NOTES)* [repeat [PE]] + | radio-send [V] + | radio-set-group [PE] + | set-variable-X [V] + | set-variable-Y [V] + | set-variable-Z [V] + | switch-page [PAGE] + + PAGE := | page-1 | page-2 | page-3 | page-4 | page-5 + SND := | giggle | happy | hello | mysterious | sad | slide | soaring + +An led image is specified inside quotes and consists of 25 digits, either 0 or 1, separated by +a space: + + IMAGE := LED-image `(0\s | 1\s)25` + + + NOTES := (C | D | E | F | G)4 ## Semantics From 1783bb98cf5087ca8e725d614737044640454f26 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Sat, 27 Dec 2025 18:16:42 -0700 Subject: [PATCH 7/9] more on semantics --- assets/strings/en/tooltips.json | 2 +- docs/doc-plan.md | 160 ++++++++++++++++++++++---------- locales/tooltips.json | 2 +- tooltips.ts | 2 +- 4 files changed, 116 insertions(+), 50 deletions(-) diff --git a/assets/strings/en/tooltips.json b/assets/strings/en/tooltips.json index 22a46d0b..2466eb4e 100644 --- a/assets/strings/en/tooltips.json +++ b/assets/strings/en/tooltips.json @@ -122,7 +122,7 @@ "T157": "3", "T158": "4", "T159": "5", - "T160": "LED image", + "T160": "image", "T161": "red", "T162": "purple", "T163": "giggle", diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 289d7c42..4931cd6d 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -3,43 +3,43 @@ ## Syntax In the following, a word in ALLCAPS refers to a non-terminal in -MicroCode's grammar. All other words are terminal symbols and -may have dashes and other symbols in them, with the following -exceptions: is a floating point number; is an -integer greater than zero; // designates a comment. +MicroCode's grammar. All other words are terminal symbols, with +the following exceptions: is a floating point number; + is an integer greater than zero; // designates a comment; +the symbols \s, \*, (, ), [, ], and | are part of the grammar +specification. Words are always separated by whitespace. -A program (PROG) consists of 5 pages, number 1-5, each with a possibly empty sequence of -rules RULE: +A program (PROG) consists of 5 pages, numbered 1-5, each with a possibly +empty sequence of rules RULE: - PROG := page-1 RULE* page-2 RULE* page-3 RULE* page-4 RULE* page-5 RULE* + PROG := page_1 RULE\* page_2 RULE\* page_3 RULE\* page_4 RULE\* page_5 RULE\* -Each rule has an option when section WHEN and an optional do section DO. +Each rule has an optional section WHEN and an optional section DO. RULE := when [WHEN] do [DO] -The WHEN section specifies an event of interest and, optionally, a filter on that event. +The WHEN section specifies a signal of interest and, optionally, a filter on that signal. The DO section specifies an action and, optionally, parameters to that action. -Some actions can be repeated. WHEN := - | page-start [TS] // fires (once) when control transitions to this page, with optional delay - | timer [TS] // set a timer to fire after a delay, execute repeatedly after associated action completes + | page_start [TS] // fires (once) when control transitions to this page, with optional delay + | timer [TS] // set a timer to fire after a delay, execute repeatedly | press [PK] // fire on press of specified button PK | release [PK] // fire on release of specified button PK | move [MK] // fire on specified accelerometer event MK | sound [loud | quiet | C] // fire on loud/quiet event or comparison C of current sound level (0-255) - | temperature [UD | C] // fire on UD event or comparison C of current temperature (in Celcius) + | temperature [UD | C] // fire on UD event or comparison C of current temperature (in Celsius) | light [UD | C] // fire on UD event or comparison C of current light level (0-255) | magnet [UD | C] // fire on UD event or comparison C of current magnetic level - | radio-receive [C] // fire when number arrives via radio, subject to optional comparison C - | variable-X-set [C] // fire after variable X has been assigned, subject to optional comparison C - | variable-Y-set [C] // fire after variable Y has been assigned, subject to optional comparison C - | variable-Z-set [C] // fire after variable Z has been assigned, subject to optional comparison C + | radio_receive [C] // fire when number arrives via radio, subject to optional comparison C + | variable_X_set [C] // fire after variable X has been assigned, subject to optional comparison C + | variable_Y_set [C] // fire after variable Y has been assigned, subject to optional comparison C + | variable_Z_set [C] // fire after variable Z has been assigned, subject to optional comparison C UD := up | down - TS := (1/4-second | 1-second | 1-random-second | 5-seconds)* // sum the sequence of times - PK := button-A | button-B | logo | pin-0 | pin-1 | pin-2 - MK := shake | tilt-left | tilt-right | ... + TS := (1/4_second | 1_second | 1_random_second | 5_seconds)\* // sum the sequence of times + PK := button_A | button_B | logo | touch_pin_0 | touch_pin_1 | touch_pin_2 + MK := shake | tilt_left | tilt_right | tilt_up | tilt_down | face_down | face_up Sensors and variables may be compared to values using C; sensors may also have events @@ -49,11 +49,11 @@ Comparison operators CO are as follows: CO := | equals - | not-equals - | less-then - | less-then-or-equal - | greater-than - | greater-than-or-equal + | not_equals + | less_then + | less_then_or_equal + | greater_than + | greater_than_or_equal An expression E is either atomic A, a binary expression, or a randomly chosen value: @@ -63,16 +63,16 @@ An expression E is either atomic A, a binary expression, or a randomly chosen va | A / E | A - E | A * E - | random PE + | random_number PE An atomic value A is either a floating point number, one of the three variables, or the current value of one of the four sensors, or the last value received over radio: A := | - | var-X | var-Y | var-Z - | light-value | sound-value | temp-value | magnet-value - | radio-value + | var_X | var_Y | var_Z + | light_value | sound_value | temp_value | magnet_value + | radio_value A positive (integer) expression PE is @@ -84,30 +84,96 @@ A positive (integer) expression PE is A DO action DO := - | show-number [V] - | show-image (IMAGE)* [repeat [PE]] - | play-sound (SND)* [repeat [PE]] - | play-music (NOTES)* [repeat [PE]] - | radio-send [V] - | radio-set-group [PE] - | set-variable-X [V] - | set-variable-Y [V] - | set-variable-Z [V] - | switch-page [PAGE] + | show_number [V] + | show_image (IMAGE)\* [repeat [PE]] + | play_sound (SND)\* [repeat [PE]] + | music (NOTES)* [repeat [PE]] + | radio_send [V] + | radio_set_group [PE] + | set_variable_X [V] + | set_variable_Y [V] + | set_variable_Z [V] + | switch_page [PAGE] - PAGE := | page-1 | page-2 | page-3 | page-4 | page-5 - SND := | giggle | happy | hello | mysterious | sad | slide | soaring + PAGE := | page_1 | page_2 | page_3 | page_4 | page_5 + SND := | giggle | happy | hello | mysterious | sad | slide | soaring -An led image is specified inside quotes and consists of 25 digits, either 0 or 1, separated by -a space: +An led image occurs inside backquotes ` and consists of 25 characters, either . or 1, separated by +whitespace: - IMAGE := LED-image `(0\s | 1\s)25` + IMAGE := image ` (.\s+ | 1\s+)25 ` +A melody fragment consists of a sequence of 4 characters from the set { C, D, E, F, G, -}, +where - denotes a rest, inside backquotes: - NOTES := (C | D | E | F | G)4 + NOTES := melody ` (C | D | E | F | G | -)4 ` ## Semantics -Before execution starts, all variables are initialized to 0 and -the current value of all micro:bit/jacdac sensors is cached. +Before execution starts, all variables (X, Y, and Z) are initialized to 0 +and the current value of all micro:bit/jacdac sensors is cached. +The initial value of the radio is undefined. +The radio group is initialized to 1. Execution begins by transitioning to page 1. + +### Defaults + +The absence of an optional element results in the use of a default, as follows: + +- A rule with an empty do section never executes (no matching performed + on it). +- A rule with an empty when section defaults to page_start signal with no delay. +- Signal defaults are as follows + - page_start defaults to no delay + - timer defaults to 1 second delay + - press defaults to wildcard (any element in PK) + - release defaults to wildcard (any element in PK) + - move defaults to shake event + - sound defaults to loud event + - temperature, light, and magnet default to up event + - radio and variable signals have no default +- Action defaults are as follows + - show_number defaults to 0 + - show_image defaults to smiley face + - play_sound defaults to giggle + - music defaults to `C E G C` + - radio_send defaults to 0 + - radio_set_group defaults to 1 + - set of a variable defaults to 0 + - switch page with no page specified is a NOOP + +### Signals + +Execution of rules on the current page is driven by the reception +of _signals_, which may come from the external environment (for +example, when the user presses a button, shakes the micro:bit, +or a sensor provides a new value) or may be generated by the +MicroCode program itself (for example, by assigning to a variable +or switching to another page). + +Regardless of their origin, signals are ordered and processed one +at a time using a FIFO queue. Each signal has a name corresponding to +the signals named in the when section; a signal carries a payload, which +may be an event or a value. Some special kinds of signals are +used for timers, as detailed later. + +### Resources and conflicts + +Actions have effects through writing to resources, which are as follows: + +- Screen +- Speaker +- Radio group +- Radio +- variable X +- variable Y +- variable Z + +If two rules have actions that target the same resource, they are said +to be in _conflict_ if it is possible for them to execute at the same time. + +### Rule matching + +Upon reception of a signal, it is first necessary to find the +rules that are enabled for execution by the signal. The first +step is to find the rules that mention the named signal. diff --git a/locales/tooltips.json b/locales/tooltips.json index ffb0dfbc..4281f4f7 100644 --- a/locales/tooltips.json +++ b/locales/tooltips.json @@ -137,7 +137,7 @@ "T158": "4", "T159": "5", - "T160": "LED image", + "T160": "image", "T161": "red", "T162": "purple", "T163": "giggle", diff --git a/tooltips.ts b/tooltips.ts index 5bade311..1b043bf5 100644 --- a/tooltips.ts +++ b/tooltips.ts @@ -114,7 +114,7 @@ namespace microcode { else if (id === "T157") res = "3"; else if (id === "T158") res = "4"; else if (id === "T159") res = "5"; - else if (id === "T160") res = "LED image"; + else if (id === "T160") res = "image"; else if (id === "T161") res = "red"; else if (id === "T162") res = "purple"; else if (id === "T163") res = "giggle"; From d2e53dec2cce8fe32b0f1bab5f2183981accb116 Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Sat, 27 Dec 2025 19:01:57 -0700 Subject: [PATCH 8/9] more semantics --- docs/doc-plan.md | 72 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 8 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index 4931cd6d..f9a1a11f 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -1,19 +1,43 @@ # The MicroCode Language +This document presents a detailed accounting of the syntax and +semantics of the MicroCode language. Its intended audience are +those who are familiar with programming languages and would like +to understand the MicroCode language in depth. We also will +use it as the basis for generating friendlier descriptions +that use MicroCode's visual presentation, as well as to +generate tests and aid in the translation of MakeCode programs +to MicroCode programs, + ## Syntax +MicroCode has a concrete syntax, as detailed below, for the +purpose of creating programs without the need for visual +MicroCode editor. + In the following, a word in ALLCAPS refers to a non-terminal in MicroCode's grammar. All other words are terminal symbols, with the following exceptions: is a floating point number; - is an integer greater than zero; // designates a comment; + is an integer greater than zero; // designates a comment +(just for use in this markdown - MicroCode does not support comments); the symbols \s, \*, (, ), [, ], and | are part of the grammar specification. Words are always separated by whitespace. -A program (PROG) consists of 5 pages, numbered 1-5, each with a possibly -empty sequence of rules RULE: +Note that non-terminals correspond to the tooltips used in MicroCode's +visual editor (where the underscores are replaced by spaces), which +accounts for their long form. + +A program (PROG) consists of 5 pages, numbered 1-5, each with a (possibly +empty) sequence of rules RULE: PROG := page_1 RULE\* page_2 RULE\* page_3 RULE\* page_4 RULE\* page_5 RULE\* +So, the following program is the empty program + +``` +page_1 page_2 page_3 page_4 page_5 +``` + Each rule has an optional section WHEN and an optional section DO. RULE := when [WHEN] do [DO] @@ -161,13 +185,14 @@ used for timers, as detailed later. Actions have effects through writing to resources, which are as follows: -- Screen -- Speaker -- Radio group -- Radio +- screen +- speaker +- radio group +- radio channel - variable X - variable Y - variable Z +- current page If two rules have actions that target the same resource, they are said to be in _conflict_ if it is possible for them to execute at the same time. @@ -176,4 +201,35 @@ to be in _conflict_ if it is possible for them to execute at the same time. Upon reception of a signal, it is first necessary to find the rules that are enabled for execution by the signal. The first -step is to find the rules that mention the named signal. +step is to find the rules that mention the named signal. Then +the optional conditions associated with those rules are evaluated +in the current state (of variable and sensor values) to prune this +set to get the enabled set E. Finally, if two rules in E are in conflict +then the rule that comes later in sequence is removed from E. + +Once we have the final set E of enabled rules, we halt +execution of any currently active rules that conflict with +a rule in E. + +The set E is then partition into three sets, I, S, and T, corresponding +to rules that execute instantly, those that switch page, and t +hose that take time. Instant actions are + +- assignments to variables +- radio send +- radio set group +- switch page + +The remaining actions are the ones that (may) take time. + +The actions in I are executed first and run to completion. +Then, if S is not empty then +it must be a singleton, so a page switch will take place, in which +case actions in T are ignored. Else, if S is empty then actions in +T are started. + +### Updating state + +### Switching pages + +### Timers From caaad34c6350db7cc00e527fcf08a7d17b33016d Mon Sep 17 00:00:00 2001 From: Thomas Ball Date: Sun, 28 Dec 2025 20:54:58 -0800 Subject: [PATCH 9/9] minor mods --- docs/doc-plan.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/doc-plan.md b/docs/doc-plan.md index f9a1a11f..24884e59 100644 --- a/docs/doc-plan.md +++ b/docs/doc-plan.md @@ -94,7 +94,7 @@ or the current value of one of the four sensors, or the last value received over A := | - | var_X | var_Y | var_Z + | variable_X | variable_Y | variable_Z | light_value | sound_value | temp_value | magnet_value | radio_value @@ -136,13 +136,13 @@ where - denotes a rest, inside backquotes: Before execution starts, all variables (X, Y, and Z) are initialized to 0 and the current value of all micro:bit/jacdac sensors is cached. -The initial value of the radio is undefined. +The initial value of radio_value is undefined. The radio group is initialized to 1. Execution begins by transitioning to page 1. ### Defaults -The absence of an optional element results in the use of a default, as follows: +The absence of an optional element/value results in the use of a default element/value, as follows: - A rule with an empty do section never executes (no matching performed on it). @@ -155,7 +155,7 @@ The absence of an optional element results in the use of a default, as follows: - move defaults to shake event - sound defaults to loud event - temperature, light, and magnet default to up event - - radio and variable signals have no default + - radio and variable signals have no default, they fire even without a default - Action defaults are as follows - show_number defaults to 0 - show_image defaults to smiley face @@ -163,8 +163,8 @@ The absence of an optional element results in the use of a default, as follows: - music defaults to `C E G C` - radio_send defaults to 0 - radio_set_group defaults to 1 - - set of a variable defaults to 0 - - switch page with no page specified is a NOOP + - variable_X_set, variable_Y_set, variable_Z_set defaults to 0 + - switch_page with no page specified is a NOOP ### Signals @@ -212,15 +212,13 @@ execution of any currently active rules that conflict with a rule in E. The set E is then partition into three sets, I, S, and T, corresponding -to rules that execute instantly, those that switch page, and t -hose that take time. Instant actions are +to rules whose actions execute instantly, those that switch page, and those that take time. Instant actions are - assignments to variables - radio send - radio set group -- switch page -The remaining actions are the ones that (may) take time. +The remaining actions (other than switch page) are the ones that (may) take time. The actions in I are executed first and run to completion. Then, if S is not empty then