2.1.28, initiation update to PXT v5.28.24 (#54)

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

@@ -7,11 +7,11 @@ Registers an event to be fired when one of the delimiter is matched.
 serial.onDataReceived(",", () => {})
 ```
 
-### Parameters
+## Parameters
 
-* `delimiters` is a [string](/reference/types/string) containing any of the character to match
+* `delimiters` is a [string](/types/string) containing any of the character to match
 
-### Example
+## Example
 
 Read values separated by `,`:
 
@@ -21,7 +21,7 @@ serial.onDataReceived(serial.delimiters(Delimiters.Comma), () => {
 })
 ```
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),

docs/reference/serial/read-buffer.md

@@ -0,0 +1,39 @@
+# read Buffer
+
+Read available serial data into a buffer.
+
+```sig
+serial.readBuffer(64);
+```
+
+## Parameters
+
+* **length**: the [number](/types/number) of characters of serial data to read.
+
+## Returns
+
+* a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
+
+## ~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.
+
+The need to pause for more data is set by the @boardname@ **[serial mode](https://lancaster-university.github.io/microbit-docs/ubit/serial/#serial-modes)**.
+## ~
+
+## Example
+
+Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
+
+```typescript
+let rowData: Buffer = null;
+for (let i = 0; i < 24; i++) {
+    rowData = serial.readBuffer(80);
+    pins.i2cWriteBuffer(65, rowData, false);
+}
+```
+
+## See Also
+
+[write buffer](/reference/serial/write-buffer)

docs/reference/serial/read-line.md

@@ -6,19 +6,19 @@ Read a line of text from the serial port.
 serial.readLine();
 ```
 
-#### ~hint
+### ~hint
 
 This function expects the line it reads to be terminated with the `\r`
 character.  If your terminal software does not terminate lines with
 `\r`, this function will probably never return a value.
 
-#### ~
+### ~
 
-### Returns
+## Returns
 
-* a [string](/reference/types/string) containing input from the serial port, such as a response typed by a user
+* a [string](/types/string) containing input from the serial port, such as a response typed by a user
 
-### Example
+## Example
 
 The following example requests the user's name, then repeats it to greet the user.
 
@@ -31,7 +31,7 @@ basic.forever(() => {
 });
 ```
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),

docs/reference/serial/read-string.md

@@ -1,16 +1,16 @@
 # Serial Read String
 
-Read the buffered serial data as a string
+Read the buffered serial data as a string.
 
 ```sig
 serial.readString();
 ```
 
-### Returns
+## Returns
 
-* a [string](/reference/types/string) containing input from the serial port. Empty if no data available.
+* a [string](/types/string) containing input from the serial port. The string is empty if no data is available.
 
-### Example
+## Example
 
 The following program scrolls text on the screen as it arrives from serial.
 
@@ -20,7 +20,7 @@ basic.forever(() => {
 });
 ```
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),

docs/reference/serial/read-until.md

@@ -0,0 +1,28 @@
+# Serial Read Until
+
+Read a text from the serial port until a delimiter is found.
+
+```sig
+serial.readUntil(",");
+```
+
+## Returns
+
+* a [string](/types/string) containing input from the serial port, such as a response typed by a user
+
+## Example
+
+The following example reads strings separated by commands (``,``).
+
+```blocks
+basic.forever(() => {
+    let answer = serial.readUntil(",");
+    serial.writeLine(answer);
+});
+```
+
+## See also
+
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write value](/reference/serial/write-value)

docs/reference/serial/redirect-to-usb.md

@@ -0,0 +1,14 @@
+# redirect To USB
+
+Direct the serial input and output to use the USB connection.
+
+The @boardname@ is set to use the USB connection for serial data by default. If serial data is currently redirected, using [redirect](/reference/serial/redirect), to the pins, you can set it back to use USB.
+
+```sig
+serial.redirectToUSB()
+```
+
+## See also
+
+[serial](/device/serial),
+[redirect](/reference/serial/redirect)

docs/reference/serial/redirect-to.md

@@ -1,31 +0,0 @@
-# Serial Redirect To
-
-Dynamically configure the serial instance to use pins other than
-``USBTX`` and ``USBRX``.
-
-```sig
-serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
-```
-
-### Parameters
-
-* ``tx``: the [serial pin](/device/pins) on which to transmit data 
-* ``rx``: the [serial pin](/device/pins) on which to receive data 
-* ``rate``: the baud rate at which to transmit and receive data (either `9600` or ``115200``)
-
-### Example
-
-When button ``A`` is pressed, the following example reconfigures the
-serial instance. The new configuration uses pin ``P1`` to transmit and
-``P2`` to receive, at a baud rate of `9600`.
-
-```blocks
-input.onButtonPressed(Button.A, () => {
-    serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
-});
-```
-
-### See also
-
-[serial](/device/serial)
-

docs/reference/serial/redirect.md

@@ -0,0 +1,44 @@
+# redirect
+
+Configure the serial port to use the pins instead of USB.
+
+```sig
+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.
+
+## Parameters
+
+* **tx**: the transmit [pin](/device/pins) to send serial data on.
+* **rx**: the receive [pin](/device/pins) to receive serial data on.
+* **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**
+
+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.
+
+When pins on your @boardname@ are configured for serial communication, they make a serial port for data. The port switches the voltage on the pins to represent a new bit to send on the wire. A series of these voltage changes eventually sends a complete byte of data. The speed at which the voltage changes create a signal to communicate the bits is called the _baud_ rate.
+
+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
+
+Change where serial data is sent to and received from. When button **A** is pressed, reconfigure the
+serial port to use the pins. The new configuration uses pin ``P1`` to transmit and
+``P2`` to receive. The baud rate is set to `9600`.
+
+```blocks
+input.onButtonPressed(Button.A, () => {
+    serial.redirect(SerialPin.P1, SerialPin.P2, BaudRate.BaudRate9600);
+});
+```
+
+## See also
+
+[serial](/device/serial),
+[redirectToUSB](/reference/serial/redirect-to-usb)
+

docs/reference/serial/set-rx-buffer-size.md

@@ -0,0 +1,23 @@
+# set Rx Buffer Size
+
+Sets the length of the serial reception buffer in bytes.
+
+```sig
+serial.setRxBufferSize(10)
+```
+
+## Parameters
+
+* **size**: desired length of the reception buffer
+
+## Example
+
+Allocates 64 bytes for the reception buffer.
+
+```typescript
+serial.setRxBufferSize(64)
+```
+
+## See also
+
+[set tx buffer size](/reference/serial/set-tx-buffer-size)

docs/reference/serial/set-tx-buffer-size.md

@@ -0,0 +1,23 @@
+# set Tx Buffer Size
+
+Sets the length of the serial transmission buffer in bytes.
+
+```sig
+serial.setTxBufferSize(10)
+```
+
+## Parameters
+
+* **size**: desired length of the transmission buffer
+
+## Example
+
+Allocates 64 bytes for the transmission buffer.
+
+```typescript
+serial.setTxBufferSize(64)
+```
+
+## See also
+
+[set rx buffer size](/reference/serial/set-rx-buffer-size)

docs/reference/serial/write-buffer.md

@@ -0,0 +1,27 @@
+# write Buffer
+
+Write a buffer to the [serial](/device/serial) port.
+
+```sig
+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.
+
+## Parameters
+
+* **buffer**: a [buffer](/types/buffer) to write to the serial port.
+
+## Example
+
+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);
+```
+
+## See also
+
+[read buffer](/reference/serial/read-buffer)

docs/reference/serial/write-line.md

@@ -1,19 +1,21 @@
 # Serial Write Line
 
-Write a string to the [serial](/device/serial) port and start a new line of text
+Write a string to the [serial](/device/serial) port and start a new line of text 
 by writing `\r\n`.
 
 ```sig
 serial.writeLine("");
 ```
 
-### Parameters
+## Parameters
 
-* `text` is the [string](/reference/types/string) to write to the serial port
+* `text` is the [string](/types/string) to write to the serial port
 
-### Example: simple serial
+## Examples
 
-This program writes the word `BOFFO` to the serial port repeatedly.
+### Simple serial
+
+Write the word `BOFFO` to the serial port repeatedly.
 
 ```blocks
 basic.forever(() => {
@@ -22,29 +24,37 @@ basic.forever(() => {
 });
 ```
 
-### Example: streaming data
+### Streaming data
 
-This program checks the
-[compass heading](/reference/input/compass-heading) and sends the
-direction to the serial port repeatedly.
+Check the [compass heading](/reference/input/compass-heading) and show the direction on the screen. Also, send both the direction and degree heading to the serial port.
 
 ```blocks
+let degrees = 0
+let direction = ""
 basic.forever(() => {
-    let heading = input.compassHeading()
-    if (heading < 45) {
-        serial.writeLine("N");
-    } else if (heading < 135) {
-        serial.writeLine("E");
-    }
-    else if (heading < 225) {
-        serial.writeLine("S");
-    }
-    else {
-        serial.writeLine("W");
+    degrees = input.compassHeading()
+    if (degrees < 45) {
+        basic.showArrow(ArrowNames.North)
+        direction = "North"
+    } else if (degrees < 135) {
+        basic.showArrow(ArrowNames.East)
+        direction = "East"
+    } else if (degrees < 225) {
+        basic.showArrow(ArrowNames.South)
+        direction = "South"
+    } else if (degrees < 315) {
+        basic.showArrow(ArrowNames.West)
+        direction = "West"
+    } else {
+        basic.showArrow(ArrowNames.North)
+        direction = "North"
     }
+    serial.writeLine(direction + " @ " + degrees + " degrees")
+    basic.pause(500)
 })
 ```
-### See also
+
+## See also
 
 [serial](/device/serial),
 [serial write number](/reference/serial/write-number),

docs/reference/serial/write-number.md

@@ -6,22 +6,22 @@ Write a number to the [serial](/device/serial) port.
 serial.writeNumber(0);
 ```
 
-### Parameters
+## Parameters
 
-* `value` is the [number](/reference/types/number) to write to the serial port
+* `value` is the [number](/types/number) to write to the serial port
 
-### Example: one through ten
+## Example: one two three
 
-This program repeatedly writes a 10-digit number to the serial port.
+This program repeatedly writes a 3-digit number to the serial port.
 
 ```blocks
 basic.forever(() => {
-    serial.writeNumber(1234567890);
+    serial.writeNumber(123);
     basic.pause(5000);
 });
 ```
 
-### Example: plot bar graph does serial
+## Example: plot bar graph does serial
 
 If you use the ``led.plotBarGraph`` function, it writes the number
 being plotted to the serial port too.
@@ -33,9 +33,10 @@ basic.forever(() => {
 })
 ```
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),
-[serial write value](/reference/serial/write-value)
+[serial write value](/reference/serial/write-value),
+[serial write numbers](/reference/serial/write-numbers)
 

docs/reference/serial/write-numbers.md

@@ -0,0 +1,45 @@
+# Serial Write Numbers
+
+Write an array of numbers to the [serial](/device/serial) port.
+
+```sig
+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)_.
+
+You can write the numbers `0` through `5` together and they will appear as one line of serial output:
+
+``0,1,2,3,4,5``
+
+This makes a line of CSV data where the commas between the numbers are the separators for each value.
+
+## Parameters
+
+* `values`: the array of [numbers](/types/number) to write to the serial port
+
+## Example: one two three
+
+This program repeatedly writes a 3-number array to the serial port.
+
+```blocks
+basic.forever(() => {
+    serial.writeNumbers([1, 2, 3]);
+    basic.pause(5000);
+});
+```
+
+## Example: plot temperature and light
+
+```blocks
+serial.writeLine("temp,light")
+basic.forever(() => {
+    serial.writeNumbers([input.temperature(), input.lightLevel()])
+})
+```
+
+## See also
+
+[serial](/device/serial),
+[serial write line](/reference/serial/write-line),
+[serial write value](/reference/serial/write-value)

docs/reference/serial/write-string.md

@@ -7,11 +7,11 @@ without starting a new line afterward.
 serial.writeString("");
 ```
 
-### Parameters
+## Parameters
 
-* `text` is the [string](/reference/types/string) to write to the serial port
+* `text` is the [string](/types/string) to write to the serial port
 
-### Example: simple serial
+## Example: simple serial
 
 This program writes the word `JUMBO` to the serial port repeatedly,
 without any new lines.
@@ -23,7 +23,7 @@ basic.forever(() => {
 });
 ```
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),

docs/reference/serial/write-value.md

@@ -1,20 +1,31 @@
-# Write Value
+# write Value
 
-Write a name/value pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
+Write a **name:value** pair and a newline character (`\r\n`) to the [serial](/device/serial) port.
 
 ```sig
 serial.writeValue("x", 0);
 ```
 
-### Parameters
+It is common when reporting or recording data to use a _Name Value Pair_ (NVP). They appear as a text output string in the form of a _name_ and a _value_ together. The name and the value are separated in the string with a _colon_, `:`. A name value pair reporting a temperature of `-15` degrees could look like:
 
-* `name` is the [string](/reference/types/string) to write to the serial port
-* `value` is the [number](/reference/types/number) to write to the serial port
+``temperature:-15``
 
+Associating a name with a value helps to identify related data when different data sources are recorded. For example, if you're reporting both temperature and light intensity, the _name:value_ format helps spreadsheets or other data analysis programs distinguish between them and group the same types of values together properly. Reporting two data sources might look like this in the output:
 
+```
+temperature:-15
+temperature:-12
+light:154
+temperature:-11
+light:152
+```
 
+## Parameters
 
-### Example: streaming data
+* `name` is the [string](/types/string) to write to the serial port
+* `value` is the [number](/types/number) to write to the serial port
+
+## Example: streaming data
 
 Every 10 seconds, the example below sends the temperature and light level
 to the serial port.
@@ -27,15 +38,15 @@ basic.forever(() => {
 })
 ```
 
-#### ~hint
+### ~hint
 
 The [send value](/reference/radio/send-value) function broadcasts
 string/number pairs.  You can use a second @boardname@ to receive them,
 and then send them directly to the serial port with ``write value``.
 
-#### ~
+### ~
 
-### See also
+## See also
 
 [serial](/device/serial),
 [serial write line](/reference/serial/write-line),