diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index fb4a1863..d11ee94c 100644 --- a/docs/SUMMARY.md +++ b/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) diff --git a/docs/reference/serial.md b/docs/reference/serial.md index f93f1d52..8d8bb992 100644 --- a/docs/reference/serial.md +++ b/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) diff --git a/docs/reference/serial/redirect-to-usb.md b/docs/reference/serial/redirect-to-usb.md index 0659f5b3..e03c8993 100644 --- a/docs/reference/serial/redirect-to-usb.md +++ b/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) diff --git a/docs/reference/serial/redirect-to.md b/docs/reference/serial/redirect-to.md deleted file mode 100644 index 04d3c42e..00000000 --- a/docs/reference/serial/redirect-to.md +++ /dev/null @@ -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) - diff --git a/docs/reference/serial/redirect.md b/docs/reference/serial/redirect.md new file mode 100644 index 00000000..4563c646 --- /dev/null +++ b/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) + diff --git a/libs/core/_locales/core-jsdoc-strings.json b/libs/core/_locales/core-jsdoc-strings.json index 1dc551e6..5eb021d7 100644 --- a/libs/core/_locales/core-jsdoc-strings.json +++ b/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", diff --git a/libs/core/serial.cpp b/libs/core/serial.cpp index 7363a1ac..a01813db 100644 --- a/libs/core/serial.cpp +++ b/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" diff --git a/libs/core/shims.d.ts b/libs/core/shims.d.ts index 4dff6d28..ab8356d7 100644 --- a/libs/core/shims.d.ts +++ b/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