Do some edits for serial redirect (#605)

* Do some edits for serial redirect

* Broken links

docs/SUMMARY.md

@@ -241,7 +241,8 @@
         * [read line](/reference/serial/read-line)
         * [read string](/reference/serial/read-string)
         * [on data received](/reference/serial/on-data-received)
-        * [redirect](/reference/serial/redirect-to)
+        * [redirect](/reference/serial/redirect)
+        * [redirect to usb](/reference/serial/redirect-to-usb)
         * [write buffer](/reference/serial/write-buffer)
         * [read buffer](/reference/serial/read-buffer)
     * [Control](/reference/control)

docs/reference/serial.md

@@ -27,5 +27,5 @@ serial.readBuffer(64);
 [writeLine](/reference/serial/write-line), [writeNumber](/reference/serial/write-number), [writeValue](/reference/serial/write-value),
 [writeString](/reference/serial/write-string), [readUntil](/reference/serial/read-until), [readLine](/reference/serial/read-line),
 [readString](/reference/serial/read-string), [onDataReceived](/reference/serial/on-data-received),
-[redirect](/reference/serial/redirect-to), [writeBuffer](/reference/serial/write-buffer), [readBuffer](/reference/serial/read-buffer),
+[redirect](/reference/serial/redirect), [writeBuffer](/reference/serial/write-buffer), [readBuffer](/reference/serial/read-buffer),
 [redirectToUSB](/reference/serial/redirect-to-usb)

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

@@ -1,6 +1,8 @@
-# Serial Redirect To USB
+# redirect To USB
 
-Dynamically configure the serial instance to use ``USBTX`` and ``USBRX``.
+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()
@@ -9,4 +11,4 @@ serial.redirectToUSB()
 ## See also
 
 [serial](/device/serial),
-[redirect](/reference/serial/redirect-to)
+[redirect](/reference/serial/redirect)

docs/reference/serial/redirect-to.md

@@ -1,32 +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),
-[redirectToUSB](/reference/serial/redirect-to-usb)
-

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)
+

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

@@ -412,17 +412,17 @@
   "serial.delimiters": "Returns the delimiter corresponding string",
   "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.readBuffer": "Reads multiple characters from the receive buffer. Pauses until enough characters are present.",
+  "serial.readBuffer": "Read multiple characters from the receive buffer. Pause until enough characters are present.",
   "serial.readBuffer|param|length": "default buffer length, eg: 64",
   "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.",
-  "serial.redirectToUSB": "Redirects the serial instance to USBTX and USBRX.",
+  "serial.redirect": "Set the serial input and output to use pins instead of the USB connection.",
+  "serial.redirectToUSB": "Direct the serial input and output to use the USB connection.",
   "serial.redirect|param|rate": "the new baud rate. eg: 115200",
   "serial.redirect|param|rx": "the new reception pin, eg: SerialPin.P1",
-  "serial.redirect|param|tx": "the new transmission pins, eg: SerialPin.P0",
+  "serial.redirect|param|tx": "the new transmission pin, eg: SerialPin.P0",
   "serial.writeBuffer": "Sends a buffer through Serial connection",
   "serial.writeLine": "Prints a line of text to the serial",
   "serial.writeNumber": "Prints a numeric value to the serial",

libs/core/serial.cpp

@@ -121,7 +121,7 @@ namespace serial {
     }
 
     /**
-    * Reads multiple characters from the receive buffer. Pauses until enough characters are present.
+    * Read multiple characters from the receive buffer. Pause until enough characters are present.
     * @param length default buffer length, eg: 64
     */
     //% blockId=serial_readbuffer block="serial|read buffer %length"
@@ -139,13 +139,13 @@ namespace serial {
     }
 
     /**
-    * Dynamically configuring the serial instance to use pins other than USBTX and USBRX.
-    * @param tx the new transmission pins, eg: SerialPin.P0
+    * Set the serial input and output to use pins instead of the USB connection.
+    * @param tx the new transmission pin, eg: SerialPin.P0
     * @param rx the new reception pin, eg: SerialPin.P1
     * @param rate the new baud rate. eg: 115200
     */
     //% weight=10
-    //% help=serial/redirect-to
+    //% help=serial/redirect
     //% blockId=serial_redirect block="serial|redirect to|TX %tx|RX %rx|at baud rate %rate"
     //% blockExternalInputs=1
     //% tx.fieldEditor="gridpicker" tx.fieldOptions.columns=3
@@ -162,7 +162,7 @@ namespace serial {
     }
 
     /**
-    * Redirects the serial instance to USBTX and USBRX.
+    * Direct the serial input and output to use the USB connection.
     */
     //% weight=9 help=serial/redirect-to-usb
     //% blockId=serial_redirect_to_usb block="serial|redirect to USB"    

libs/core/shims.d.ts

@@ -811,7 +811,7 @@ declare namespace serial {
     function writeBuffer(buffer: Buffer): void;
 
     /**
-     * Reads multiple characters from the receive buffer. Pauses until enough characters are present.
+     * Read multiple characters from the receive buffer. Pause until enough characters are present.
      * @param length default buffer length, eg: 64
      */
     //% blockId=serial_readbuffer block="serial|read buffer %length"
@@ -819,13 +819,13 @@ declare namespace serial {
     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
+     * Set the serial input and output to use pins instead of the USB connection.
+     * @param tx the new transmission pin, eg: SerialPin.P0
      * @param rx the new reception pin, eg: SerialPin.P1
      * @param rate the new baud rate. eg: 115200
      */
     //% weight=10
-    //% help=serial/redirect-to
+    //% help=serial/redirect
     //% blockId=serial_redirect block="serial|redirect to|TX %tx|RX %rx|at baud rate %rate"
     //% blockExternalInputs=1
     //% tx.fieldEditor="gridpicker" tx.fieldOptions.columns=3
@@ -836,7 +836,7 @@ declare namespace serial {
     function redirect(tx: SerialPin, rx: SerialPin, rate: BaudRate): void;
 
     /**
-     * Redirects the serial instance to USBTX and USBRX.
+     * Direct the serial input and output to use the USB connection.
      */
     //% weight=9 help=serial/redirect-to-usb
     //% blockId=serial_redirect_to_usb block="serial|redirect to USB" shim=serial::redirectToUSB