pxt-microbit 5.0.12 → 5.1.2

package/docs/projects/v2-cat-napping.md

@@ -0,0 +1,219 @@
+# Cat Napping
+
+## 1. Introduction @unplugged
+
+Lychee the cat loves the sun and wants to know if your home has a good sunbathing spot. Are you up for the challenge?
+
+![Cat Tanning banner message, an image of a cat](/static/mb/projects/cat-napping/1_lychee.png)
+
+## 2. Setting logging to false on start
+
+📋 **Variable data** 📋
+
+First, we want to make sure we know when our micro:bit is collecting data. To do this, let's create a [__*boolean*__](#boolean "something that is only true or false") [__*variable*__](#variable "a holder for information that may change") and use it to track when the @boardname@ is logging data. We'll start with the logging variable set to false.
+
+---
+
+► In the ``||variables:Variables||`` category, click on ``Make a Variable...`` and make a variable named ``logging``.
+
+► From the ``||variables:Variables||`` category, grab the ``||variables:set [logging] to [0]||`` block and snap it into the empty ``||basic:on start||`` container.
+
+► From the ``||logic:Logic||`` category, grab a ``||logic:<false>||`` argument and snap it in to **replace** the ``||variables:[0]||`` value in your ``||variables:set [logging] to [0]||`` statement.
+
+```blocks
+let logging = false
+logging = false
+```
+
+## 3. Toggle logging on A press
+
+▶️ **Starting and stopping** ⏸️
+
+Let's give Lychee some control over when she wants to start and stop logging data on the @boardname@.
+
+---
+
+► From the ``||input:Input||`` category, grab a ``||input:on button [A] pressed||`` container and drag it into your workspace.
+
+► From the ``||variables:Variables||`` category, grab a ``||variables:set [logging] to [0]||`` block and snap it inside of your ``||input:on button [A] pressed||`` container.
+
+► From the ``||logic:Logic||`` category, grab a ``||logic:<not []>||`` argument and snap it in to **replace** the ``0`` argument.
+
+► From the ``||variables:Variables||`` category, grab a ``||variables:logging||`` variable and snap it in to **replace** the empty ``||logic:<>||`` in the ``||logic:not <>||`` statement.
+
+✋🛑 Take a moment to help Lychee answer the following question: _What is happening every time she presses the A button?_
+
+```blocks
+let logging = false
+input.onButtonPressed(Button.A, function () {
+    logging = !(logging)
+})
+```
+
+## 4. Visual logging indicators
+
+👀 **Visual indicators** 👀
+
+It would help to know when the @boardname@ is logging data and when it isn't. For this step, we will be building out a visual indicator using an [__*if then / else*__](#ifthenelse "runs some code if a boolean condition is true and different code if the condition is false") statement.
+
+---
+
+► From the ``||logic:Logic||`` category, grab an ``||logic:if <true> then / else||`` statement and snap it in at the **bottom** of your ``||input:on button [A] pressed||`` container.
+
+► From ``||variables:Variables||``, grab a ``||variables:logging||`` variable and snap it in to **replace** the ``||logic:<true>||`` condition in your ``||logic:if then / else||`` statement.
+
+► Let's display an image when the @boardname@ is logging data. From the ``||basic:Basic||`` category, grab a ``||basic:show icon []||`` block and snap it into the empty **top container** of your ``||logic:if then / else||`` statement.
+
+► Set it to show the "target" icon (it looks like an empty sun - scroll down to find it!).  This will show whenever your @boardname@ is collecting data. <br />
+💡 In the ``show icon`` dropdown menu options, you can hover to see what each design is called.
+
+```blocks
+let logging = false
+input.onButtonPressed(Button.A, function () {
+    logging = !(logging)
+    if (logging) {
+        basic.showIcon(IconNames.Target)
+    } else {
+    }
+})
+```
+
+## 4. Auditory logging indicators
+
+Let's now add an auditory indicator that your @boardname@ is logging data!
+
+---
+
+► From the ``||music:Music||`` category, grab a ``||music:play sound [giggle] [until done]||`` block and snap it into the **bottom** of the **top container** of your ``||logic:if then / else||`` statement.
+
+► Click on the ``giggle`` dropdown and select ``hello``. Your block should now say ``||music:play sound [hello] [until done]||``.
+
+► Let's clear the board when the @boardname@ is not logging data. From the ``||basic:Basic||`` category, grab a ``||basic:clear screen||`` block and snap it into the empty **bottom container** of your ``||logic:if then / else||`` statement.
+
+```blocks
+let logging = false
+input.onButtonPressed(Button.A, function () {
+    logging = !(logging)
+    if (logging) {
+        basic.showIcon(IconNames.Target)
+        music.playSoundEffect(music.builtinSoundEffect(soundExpression.hello), SoundExpressionPlayMode.UntilDone)
+    } else {
+        basic.clearScreen()
+    }
+})
+```
+
+## 5. Time interval for data logging
+
+📈 **A data point a minute** 📈
+
+Let's set up the data logging for Lychee! In order to get Lychee a good amount of data without running out of memory, we should collect one data point for her every minute.
+
+---
+
+► From the ``||loops:Loops||`` category, grab a ``||loops:every [500] ms||`` container and add it to your workspace.
+
+► Click on the the ``500`` dropdown and select ``1 minute``. <br />
+💡 1 minute is equivalent to 60000ms, which is what the number will automatically change to.
+
+```blocks
+loops.everyInterval(60000, function () {
+})
+```
+
+## 6. Setting up a logging variable
+
+Now, let's use an [__*if then*__](#ifthen "runs some code if a boolean condition is true") statement to track when the @boardname@ is logging data.
+
+---
+
+► From the ``||logic:Logic||`` category, grab a ``||logic:if <true> then||`` statement and snap it into your ``||loops:every [600000] ms||`` container.
+
+► From the ``||variables:Variables||`` category, drag out a ``||variables:logging||`` variable and snap it in to **replace** the ``||logic:<true>||`` argument in the ``||logic:if <true> then||`` statement.
+
+```blocks
+let logging = false
+loops.everyInterval(60000, function () {
+    if (logging) {
+    }
+})
+```
+
+## 7. Setting up logging - Part 1
+
+🏁 **Ready...set...log!** 🏁
+
+Lychee loves her sun spots because they provide a nice, sunny and warm place to nap. So, we'll need to measure the **temperature** and **light** in different places around the house.
+
+---
+
+► From the ``||datalogger:Data Logger||`` category, grab a ``||datalogger:log data [column [""] value [0]] +||`` block and snap it **inside** the ``||logic:if [logging] then||`` statement.
+
+► Click on the ``""`` after the word ``column`` and type in "``temp``".
+
+► From the ``||input:Input||`` category, select the ``||input:temperature (°C)||`` parameter and drag it in to **replace** the ``0`` after the word ``value``.
+
+```blocks
+let logging = false
+loops.everyInterval(60000, function () {
+    if (logging) {
+        //@highlight
+        datalogger.log(
+            datalogger.createCV("temp", input.temperature())
+        )
+    }
+})
+```
+
+## 8. Setting up logging - Part 2
+
+► On the right of the ``||input:temperature (°C)||`` input that you just snapped in, there is a ➕ button. Click on it. You should now see a new row that says ``||datalogger:column [""] value [0]||``.
+
+► Click on the empty ``""`` after the word ``column`` and type in "``light``".
+
+► From the ``||input:Input||`` category, select the ``||input:light level||`` parameter and drag it in to **replace** the ``0`` parameter after the word ``value``.
+
+```blocks
+let logging = false
+loops.everyInterval(60000, function () {
+    if (logging) {
+        //@highlight
+        datalogger.log(
+            datalogger.createCV("temp", input.temperature()),
+            datalogger.createCV("light", input.lightLevel())
+        )
+    }
+})
+```
+
+## 9. Time to log data! @unplugged
+
+🎉 **Time to log data!** 🎉
+
+You did it! If you have a @boardname@ V2 (the one with the **shiny gold** logo at the top), download this code and try it out!
+
+---
+
+► Find a sun spot in your house and press the ``A`` button to start logging data - your display should show an icon and play a sound to indicate that you are logging data.
+
+► After some time (we recommend at least an hour), press the ``A`` button again to stop logging data - your display should clear to indicate that you are not logging data.
+
+## 10. Reviewing your data @unplugged
+
+🕵️ **Reviewing your data** 🕵️
+
+Now that you have logged some data, plug your @boardname@ into a laptop or desktop computer. The @boardname@ will appear like a USB drive called MICROBIT. Look in there and you'll see a file called MY_DATA:
+
+![MY_DATA file highlighted in file folder](/static/mb/projects/cat-napping/11_mydata.png)
+
+Double-click on MY_DATA to open it in a web browser and you'll see a table with your data:
+
+![Image of sample data file](/static/mb/projects/cat-napping/11_datafile.png)
+
+## 11. Lychee's preferences @unplugged
+
+Does your home have a good sunbathing spot for Lychee? Compare the light and temperature levels you record for different areas around your house! The sunniest and warmest spots will likely be her favorite ☀️😻
+
+```package
+datalogger
+```

package/docs/projects.md

@@ -68,6 +68,11 @@
         "url": "/courses",
         "imageUrl": "/static/courses/csintro.jpg"
     },
+    {
+        "name": "Jacdac",
+        "url": "/jacdac",
+        "imageUrl": "/static/jacdac/getting-started.jpg"
+    },
     {
         "name": "Behind the MakeCode Hardware",
         "url": "/behind-the-makecode-hardware",
@@ -111,6 +116,7 @@
 [Turtle](/projects/turtle),
 [Blocks to JavaScript](/courses/blocks-to-javascript),
 [Courses](/courses),
+[Jacdac](/jacdac),
 [Behind the MakeCode Hardware](/behind-the-makecode-hardware),
 [Science Experiments](/science-experiments),
 [Coding for Teachers](/coding-for-teachers),

package/docs/reference/input/logo-is-pressed.md

@@ -39,4 +39,4 @@ basic.forever(function () {
 [micro:bit V2](/device/v2),
 [on logo event](/reference/input/on-logo-event),
 [pin is pressed](/referene/inpu/pin-is-pressed),
-[touch set mode](/referene/inpu/touch-set-mode)
+[touch set mode](/reference/pins/touch-set-mode)

package/docs/reference/input/on-logo-event.md

@@ -35,4 +35,4 @@ input.onLogoEvent(TouchButtonEvent.Pressed, function () {
 [micro:bit V2](/device/v2),
 [logo is pressed](/reference/input/logo-is-pressed),
 [on pin pressed](/reference/input/on-logo-released),
-[touch set mode](/referene/inpu/touch-set-mode)
+[touch set mode](/reference/pins/touch-set-mode)

package/docs/reference/serial/on-data-received.md

@@ -4,7 +4,7 @@ Registers an event to be fired when one of the delimiter is matched.
 
 
 ```sig
-serial.onDataReceived(",", () => {})
+serial.onDataReceived(",", function() {})
 ```
 
 ## Parameters

package/docs/reference/serial/read-buffer.md

@@ -3,7 +3,7 @@
 Read available serial data into a buffer.
 
 ```sig
-serial.readBuffer(64);
+serial.readBuffer(64)
 ```
 
 ## Parameters
@@ -16,13 +16,15 @@ Use ``0`` to return the available buffered data.
 * a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
 The length is 0 if any error occurs.
 
-## ~hint
-**Pause for more data**
+### ~ hint
+
+#### Pause for more data
 
 If the desired number of characters are available, **readBuffer** returns a buffer with the expected size. If not, the calling fiber (the part of your program calling the **readBuffer** function) sleeps until the desired number of characters are finally read into the buffer.
 
 To avoid waiting for data, set the length to ``0`` so that buffered data is returned immediately.
-## ~
+
+### ~
 
 ## Example
 
@@ -31,7 +33,7 @@ Read character data from the serial port one row at a time. Write the rows to an
 ```typescript
 serial.setRxBufferSize(10)
 for (let i = 0; i < 24; i++) {
-    let rowData = serial.readBuffer(10);
+    let rowData = serial.readBuffer(10)
     pins.i2cWriteBuffer(65, rowData, false);
 }
 ```
@@ -42,14 +44,13 @@ Read available data and process it as it comes.
 
 ```typescript
 basic.forever(function() {
-    let rowData = serial.readBuffer(0);
+    let rowData = serial.readBuffer(0)
     if (rowData.length > 0) {
         // do something!!!
     }
 })
 ```
 
-
 ## See Also
 
 [write buffer](/reference/serial/write-buffer)

package/docs/reference/serial/read-line.md

@@ -3,13 +3,15 @@
 Read a line of text from the serial port.
 
 ```sig
-serial.readLine();
+serial.readLine()
 ```
 
 ### ~hint
 
+#### Newline characters
+
 This function expects the line it reads to be terminated with the `\n`
-character.  If your terminal software does not terminate lines with
+character. If your terminal software does not terminate lines with
 `\n`, this function will probably never return a value.
 
 
@@ -27,11 +29,11 @@ The following example requests the user's name, then repeats it to greet the use
 
 ```blocks
 basic.forever(() => {
-    serial.writeLine("What is your name?");
+    serial.writeLine("What is your name?")
     let answer = serial.readLine();
-    serial.writeString("Hello,");
-    serial.writeLine(answer);
-});
+    serial.writeString("Hello,")
+    serial.writeLine(answer)
+})
 ```
 
 ## See also

package/docs/reference/serial/read-string.md

@@ -3,7 +3,7 @@
 Read the buffered serial data as a string.
 
 ```sig
-serial.readString();
+serial.readString()
 ```
 
 ## Returns
@@ -15,9 +15,9 @@ serial.readString();
 The following program scrolls text on the screen as it arrives from serial.
 
 ```blocks
-basic.forever(() => {
-    basic.showString(serial.readString());
-});
+basic.forever(function() {
+    basic.showString(serial.readString())
+})
 ```
 
 ## See also

package/docs/reference/serial/read-until.md

@@ -3,7 +3,7 @@
 Read a text from the serial port until a delimiter is found.
 
 ```sig
-serial.readUntil(",");
+serial.readUntil(",")
 ```
 
 ## Returns
@@ -16,9 +16,9 @@ The following example reads strings separated by commands (``,``).
 
 ```blocks
 basic.forever(() => {
-    let answer = serial.readUntil(",");
-    serial.writeLine(answer);
-});
+    let answer = serial.readUntil(",")
+    serial.writeLine(answer)
+})
 ```
 
 ## See also

package/docs/reference/serial/redirect.md

@@ -3,7 +3,7 @@
 Configure the serial port to use the pins instead of USB.
 
 ```sig
-serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
+serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200)
 ```
 The default connection for the serial port is over a USB cable. You can have the serial data go across wires connected to pins on the @boardname@ instead. To set the input and output for the serial connection to be on the pins, you redirect it to the pins. Also, you decide how fast you want to send and receive the data on the pins by choosing a _baud_ rate.
 
@@ -14,8 +14,9 @@ The default connection for the serial port is over a USB cable. You can have the
 * **rate**: the baud rate for transmitting and receiving data. Baud rates you can choose from are:
 >`300`, `1200`, `2400`, `4800`, `9600`, `14400`, `19200,`, `28800`, `31250`, `38400`, `57600`, or `115200`
 
-## ~hint
-**Baud rate**
+### ~hint
+
+#### Baud rate
 
 Serial communication transmits data by sending one bit of a [digital number](/types/buffer/number-format) (usually a byte sized number), at a time. So, the data bytes are sent as a series of their bits. Serial communication uses just one wire to send these bits so only one bit can travel across the wire at a time.
 
@@ -23,7 +24,7 @@ When pins on your @boardname@ are configured for serial communication, they make
 
 You will typically use `9600` or `115200` for your baud rate. Sometimes the device you connect to can figure out what your baud rate is. Most of the time though, you need to make sure the device you connect to is set to match your baud rate.
 
-## ~
+### ~
 
 ## Example
 
@@ -32,9 +33,9 @@ serial port to use the pins. The new configuration uses pin ``P1`` to transmit a
 ``P2`` to receive. The baud rate is set to `9600`.
 
 ```blocks
-input.onButtonPressed(Button.A, () => {
-    serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
-});
+input.onButtonPressed(Button.A, function() {
+    serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600)
+})
 ```
 
 ## See also

package/docs/reference/serial/set-baud-rate.md

@@ -0,0 +1,56 @@
+# set Baud Rate
+
+Set the baud rate of the serial connection.
+
+```sig
+serial.setBaudRate(BaudRate.BaudRate115200)
+```
+
+The baud rate of the serial connection is the speed at which it will transmit data. You can set one of several standard rates for the transmit speed. The receiving @boardname@ or device must be set to receive data at the same speed as the sending @boardname@.
+
+### ~ hint
+
+#### Bits and bauds
+
+Baud, or _baud rate_, is a very old measure of data speed. It originates from the early days of _teletype_ when characters of the alphabet were transmitted over telegraph wires. Signal changes on the wires are used to encode a sequence of bits that represented a character in a message. The baud rate is how many times per second these signal changes happen. When binary data (digital bits) is transmitted over an analog system, like telegraph or telephone wires, the bits are _modulated_ by
+a signal changing scheme to represent them. Sometimes mutliple bits are transmitted in a signal
+change which makes the actual _bit rate_ faster than the baud rate.
+
+### ~
+
+## Parameters
+
+* **rate**: The baud rate to set for the serial connection. The default rate is `115200` baud, The rates to choose from are:
+>* `1200` baud
+>* `2400` baud
+>* `4800` baud
+>* `9600` baud
+>* `14400` baud
+>* `19200` baud
+>* `28800` baud
+>* `31250` baud
+>* `38400` baud
+>* `57600` baud
+>* `115200` baud
+
+### ~reminder
+
+#### Logging serial data
+
+In order for the serial console log to record your serial data, the baud rate MUST remain
+at `115200` (the default).
+
+### ~
+
+## Example
+
+Set the baud rate to `9600` and send a message over USB serial to a computer.
+
+```blocks
+serial.setBaudRate(BaudRate.BaudRate9600)
+serial.writeString("This is my SERIAL message!")
+```
+
+## See also
+
+[redirect](/reference/serial/redirect)

package/docs/reference/serial/set-write-line-padding.md

@@ -0,0 +1,51 @@
+# set Write Line Padding
+
+Sets the padding length for text lines written to the serial port.
+
+```sig
+serial.setWriteLinePadding(0)
+```
+
+When text is written to the serial port as a "line", it can have an amount of padding to keep the line at a certian length. If the write line padding is set to `32` and the length of text sent with [write line](/reference/serial/write-line) is only `15` characters, then additional `space` characters are added to make the line length `32` characters.
+
+Also, the padding length will account for the NEWLINE characters that terminate the line.
+
+### ~ hint
+
+#### Serial input buffers
+
+Some devices that you connect a @boardname@ to with the serial port might collect the text you send to them in a buffer before they transfer it to a program that will process it. You can ensure that the connected device will respond to your messege by using padding to make the text you sent transfer out of the connected device's input buffer right away. If you know that the device connected to your @boardname@ will release the text in its input buffer when `64` characters are collected, you can set the write line padding length to `64` before you send your message.
+
+### ~
+
+In this example, the a line of text `"Hello Serial!"` is written to the serial port.
+
+```block
+serial.setWriteLinePadding(24)
+serial.writeLine("Hello Serial!")
+```
+
+In this case, the output will NOT be:
+
+`Hello Serial!\r\n`
+
+Instead, it will include addtional space characters to make the line length `24` characters:
+
+`Hello Serial!           \r\n`
+
+## Parameters
+
+* **length**: a [number](/types/number) between `0` and `128` that sets the padding length for lines of text written to the serial port. The default padding length is `32`.
+
+## Example
+
+Set the write line padding to `48` characters and write a message line to the serial port.
+
+```block
+serial.setWriteLinePadding(48)
+serial.writeString("This is my SERIAL message!")
+```
+
+## See also
+
+[write line](/reference/serial/write-line)

package/docs/reference/serial/write-buffer.md

@@ -3,7 +3,7 @@
 Write a buffer to the [serial](/device/serial) port.
 
 ```sig
-serial.writeBuffer(pins.createBuffer(0));
+serial.writeBuffer(pins.createBuffer(0))
 ```
 
 You place your data characters into an existing buffer. All of the data, the length of the buffer, is written to the serial port.
@@ -17,9 +17,9 @@ You place your data characters into an existing buffer. All of the data, the len
 Read some characters of data from a device connected to the I2C pins. Write the data to the serial port.
 
 ```typescript
-pins.i2cWriteNumber(132, NumberFormat.UInt8LE, 0);
-let i2cBuffer = pins.i2cReadBuffer(132, 16, false);
-serial.writeBuffer(i2cBuffer);
+pins.i2cWriteNumber(132, NumberFormat.UInt8LE, 0)
+let i2cBuffer = pins.i2cReadBuffer(132, 16, false)
+serial.writeBuffer(i2cBuffer)
 ```
 
 ## See also

package/docs/reference/serial/write-line.md

@@ -4,7 +4,7 @@ Write a string to the [serial](/device/serial) port and start a new line of text
 by writing `\r\n`.
 
 ```sig
-serial.writeLine("");
+serial.writeLine("")
 ```
 
 ## Parameters
@@ -18,10 +18,10 @@ serial.writeLine("");
 Write the word `BOFFO` to the serial port repeatedly.
 
 ```blocks
-basic.forever(() => {
-    serial.writeLine("BOFFO");
-    basic.pause(5000);
-});
+basic.forever(function() {
+    serial.writeLine("BOFFO")
+    basic.pause(5000)
+})
 ```
 
 ### Streaming data
@@ -31,7 +31,7 @@ Check the [compass heading](/reference/input/compass-heading) and show the direc
 ```blocks
 let degrees = 0
 let direction = ""
-basic.forever(() => {
+basic.forever(function() {
     degrees = input.compassHeading()
     if (degrees < 45) {
         basic.showArrow(ArrowNames.North)

package/docs/reference/serial/write-number.md

@@ -3,7 +3,7 @@
 Write a number to the [serial](/device/serial) port.
 
 ```sig
-serial.writeNumber(0);
+serial.writeNumber(0)
 ```
 
 ## Parameters
@@ -15,9 +15,9 @@ serial.writeNumber(0);
 This program repeatedly writes a 3-digit number to the serial port.
 
 ```blocks
-basic.forever(() => {
-    serial.writeNumber(123);
-    basic.pause(5000);
+basic.forever(function() {
+    serial.writeNumber(123)
+    basic.pause(5000)
 });
 ```
 
@@ -27,9 +27,9 @@ If you use the ``led.plotBarGraph`` function, it writes the number
 being plotted to the serial port too.
 
 ```blocks
-basic.forever(() => {
+basic.forever(function() {
     led.plotBarGraph(input.lightLevel(), 255)
-    basic.pause(10000);
+    basic.pause(10000)
 })
 ```
 

package/docs/reference/serial/write-numbers.md

@@ -3,7 +3,7 @@
 Write an array of numbers to the [serial](/device/serial) port.
 
 ```sig
-serial.writeNumbers([0, 1, 2]);
+serial.writeNumbers([0, 1, 2])
 ```
 
 Instead of writing a single number at a time using [write number](/reference/serial/write-number), you can write multiple numbers to the serial port at once. They are written as _Comma Separated Values (CSV)_.
@@ -23,17 +23,17 @@ This makes a line of CSV data where the commas between the numbers are the separ
 This program repeatedly writes a 3-number array to the serial port.
 
 ```blocks
-basic.forever(() => {
-    serial.writeNumbers([1, 2, 3]);
-    basic.pause(5000);
-});
+basic.forever(function() {
+    serial.writeNumbers([1, 2, 3])
+    basic.pause(5000)
+})
 ```
 
 ## Example: plot temperature and light
 
 ```blocks
 serial.writeLine("temp,light")
-basic.forever(() => {
+basic.forever(function() {
     serial.writeNumbers([input.temperature(), input.lightLevel()])
 })
 ```