support for serial read/write buffer (#384)

docs/reference/serial.md

@@ -10,10 +10,17 @@ serial.writeString("");
 serial.readUntil(",");
 serial.readLine();
 serial.readString();
-serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
 serial.onDataReceived(",", () => {})
 ```
 
+### Advanced
+
+```cards
+serial.redirect(SerialPin.P0, SerialPin.P0, BaudRate.BaudRate115200);
+serial.writeBuffer(pins.createBuffer(0));
+serial.readBuffer(64);
+```
+
 ### See Also
 
 [writeLine](/reference/serial/write-line), [writeNumber](/reference/serial/write-number), [writeValue](/reference/serial/write-value), [writeString](/reference/serial/write-string), [readLine](/reference/serial/read-line), [redirect](/reference/serial/redirect-to)

docs/reference/serial/read-buffer.md

@@ -0,0 +1,12 @@
+# Serial Read Buffer
+
+Read the buffered serial data as a buffer
+
+```sig
+serial.readBuffer(64);
+```
+
+### Returns
+
+* a Buffer containing input from the serial port. Empty if no data available.
+

docs/reference/serial/write-buffer.md

@@ -0,0 +1,11 @@
+# Serial Write Buffer
+
+Write a buffer to the [serial](/device/serial) port.
+
+```sig
+serial.writeBuffer(pins.createBuffer(0));
+```
+
+### Parameters
+
+* `buffer` is the buffer to write to the serial port

libs/core/serial.cpp

@@ -1,5 +1,7 @@
 #include "pxt.h"
 
+#define MICROBIT_SERIAL_READ_BUFFER_LENGTH 64
+
 enum SerialPin {
     P0 = MICROBIT_ID_IO_P0,
     P1 = MICROBIT_ID_IO_P1,
@@ -101,9 +103,39 @@ namespace serial {
     //% weight=87
     //% blockId=serial_writestring block="serial|write string %text"
     void writeString(StringData *text) {
+      if (!text) return;
+
       uBit.serial.send(ManagedString(text));
     }
 
+    /**
+    * Sends a buffer through Serial connection
+    */
+    //% help=serial/write-buffer advanced=true weight=6
+    void writeBuffer(Buffer buffer) {
+      if (!buffer) return;
+
+      ManagedBuffer buf(buffer);
+      uBit.serial.send(buf.getBytes(), buf.length());
+    }
+
+    /**
+    * Reads multiple characters from the rxBuff and fills a user buffer.
+    * @param length default buffer length, eg: 64
+    */
+    //% help=serial/read-buffer advanced=true weight=5
+    Buffer readBuffer(int length) {
+      if (length <= 0)
+        length = MICROBIT_SERIAL_READ_BUFFER_LENGTH;
+        
+      ManagedBuffer buf(length);
+      int read = uBit.serial.read(buf.getBytes(), buf.length());
+      if (read != buf.length())
+        buf = buf.slice(read);
+
+      return buf.leakData();
+    }
+
     /**
     * Dynamically configuring the serial instance to use pins other than USBTX and USBRX.
     * @param tx the new transmission pins, eg: SerialPin.P0

libs/core/shims.d.ts

@@ -714,6 +714,19 @@ declare namespace serial {
     //% blockId=serial_writestring block="serial|write string %text" shim=serial::writeString
     function writeString(text: string): void;
 
+    /**
+     * Sends a buffer through Serial connection
+     */
+    //% help=serial/write-buffer advanced=true weight=6 shim=serial::writeBuffer
+    function writeBuffer(buffer: Buffer): void;
+
+    /**
+     * Reads multiple characters from the rxBuff and fills a user buffer.
+     * @param length default buffer length, eg: 64
+     */
+    //% help=serial/read-buffer advanced=true weight=5 shim=serial::readBuffer
+    function readBuffer(length: number): Buffer;
+
     /**
      * Dynamically configuring the serial instance to use pins other than USBTX and USBRX.
      * @param tx the new transmission pins, eg: SerialPin.P0