Serial events (#337)

* added "serial->on data received"

* updated info

* updated docs

* added readline to read entire buffer

* lazy initialize of serial buffers

* init async on event

* updated docs

libs/core/_locales/core-jsdoc-strings.json

@@ -238,8 +238,10 @@
   "pins.spiWrite|param|value": "Data to be sent to the SPI slave",
   "serial": "Reading and writing data over a serial connection.",
   "serial.delimiters": "Returns the delimiter corresponding string",
-  "serial.onLineReceived": "Registers an event to be fired when a line has been received",
+  "serial.onDataReceived": "Registers an event to be fired when one of the delimiter is matched.",
+  "serial.onDataReceived|param|delimiters": "the characters to match received characters against.",
   "serial.readLine": "Reads a line of text from the serial port.",
+  "serial.readString": "Reads the buffered received data as a string",
   "serial.readUntil": "Reads a line of text from the serial port and returns the buffer when the delimiter is met.",
   "serial.readUntil|param|delimiter": "text delimiter that separates each text chunk",
   "serial.redirect": "Dynamically configuring the serial instance to use pins other than USBTX and USBRX.",

libs/core/_locales/core-strings.json

@@ -181,7 +181,9 @@
   "pins.spiWrite|block": "spi write %value",
   "pins|block": "pins",
   "serial.delimiters|block": "%del",
+  "serial.onDataReceived|block": "serial|on data received %delimiters=serial_delimiter_conv",
   "serial.readLine|block": "serial|read line",
+  "serial.readString|block": "serial|read string",
   "serial.readUntil|block": "serial|read until %delimiter=serial_delimiter_conv",
   "serial.redirect|block": "serial|redirect to|TX %tx|RX %rx|at baud rate %rate",
   "serial.writeLine|block": "serial|write line %text",

libs/core/serial.cpp

@@ -51,24 +51,27 @@ namespace serial {
     }
 
     /**
-     * Reads a line of text from the serial port.
-     */
-    //% help=serial/read-line
-    //% blockId=serial_read_line block="serial|read line"
-    //% weight=20 blockGap=8
-    StringData* readLine() {
-      return readUntil(ManagedString("\n").leakData());
+    * Reads the buffered received data as a string
+    */
+    //% blockId=serial_read_buffer block="serial|read string"
+    //% weight=18
+    StringData* readString() {
+      int n = uBit.serial.getRxBufferSize();
+      if (n == 0) return ManagedString("").leakData();
+      return ManagedString(uBit.serial.read(n, MicroBitSerialMode::ASYNC)).leakData();
     }
 
     /**
-    * Registers an event to be fired when one of the delimiter is matched
-    * @param delimiters the characters to match received characters against. eg:"\n"
+    * Registers an event to be fired when one of the delimiter is matched.
+    * @param delimiters the characters to match received characters against.
     */
-    // help=serial/on-data-received
-    // weight=18
+    //% help=serial/on-data-received
+    //% weight=18 blockId=serial_on_data_received block="serial|on data received %delimiters=serial_delimiter_conv"
     void onDataReceived(StringData* delimiters, Action body) {
       uBit.serial.eventOn(ManagedString(delimiters));
       registerWithDal(MICROBIT_ID_SERIAL, MICROBIT_SERIAL_EVT_DELIM_MATCH, body);
+      // lazy initialization of serial buffers
+      uBit.serial.read(MicroBitSerialMode::ASYNC);
     }
 
     /**

libs/core/serial.ts

@@ -38,20 +38,20 @@ namespace serial {
     }
 
     /**
-    * Registers an event to be fired when a line has been received
-    */
-    // help=serial/on-line-received
-    // blockId=serial_on_line_received block="serial on line received"
-    // weight=21 blockGap=8
-    export function onLineReceived(body: Action): void {
-       // serial.onDataReceived("\n", body);
+     * Reads a line of text from the serial port.
+     */
+    //% help=serial/read-line
+    //% blockId=serial_read_line block="serial|read line"
+    //% weight=20 blockGap=8
+    export function readLine(): string {
+        return serial.readUntil(delimiters(Delimiters.NewLine));
     }
 
     /**
      * Returns the delimiter corresponding string
      */
     //% blockId="serial_delimiter_conv" block="%del"
-    //% weight=1
+    //% weight=1 blockHidden=true
     export function delimiters(del: Delimiters): string {
         // even though it might not look like, this is more
         // (memory) efficient than the C++ implementation, because the

libs/core/shims.d.ts

@@ -715,12 +715,19 @@ declare namespace serial {
     function readUntil(delimiter: string): string;
 
     /**
-     * Reads a line of text from the serial port.
+     * Reads the buffered received data as a string
      */
-    //% help=serial/read-line
-    //% blockId=serial_read_line block="serial|read line"
-    //% weight=20 blockGap=8 shim=serial::readLine
-    function readLine(): string;
+    //% blockId=serial_read_buffer block="serial|read string"
+    //% weight=18 shim=serial::readString
+    function readString(): string;
+
+    /**
+     * Registers an event to be fired when one of the delimiter is matched.
+     * @param delimiters the characters to match received characters against.
+     */
+    //% help=serial/on-data-received
+    //% weight=18 blockId=serial_on_data_received block="serial|on data received %delimiters=serial_delimiter_conv" shim=serial::onDataReceived
+    function onDataReceived(delimiters: string, body: () => void): void;
 
     /**
      * Sends a piece of text through Serial connection.