diff --git a/docs/reference/radio/receive-string.md b/docs/reference/radio/receive-string.md new file mode 100644 index 00000000..5f4db239 --- /dev/null +++ b/docs/reference/radio/receive-string.md @@ -0,0 +1,67 @@ +# Receive String + +Reads the next radio packet if any and returns the first string. + +## Important Security Consideration + +The functions in the ``radio`` namespace allow the BBC micro:bit to communicate with other micro:bits. + +This API does not contain any form of encryption, authentication or authorization. It's purpose is solely for use as a teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + +For serious applications, BLE should be considered a substantially more secure alternative. + +```sig +radio.receiveString() +``` + +### Return value + +* the first [string](/reference/types/string) of the packet if any. ```""``` otherwise. + +### Examples + +Read the string broadcasted by other micro:bits and display it. + +```blocks +radio.onDataReceived(() => { + basic.showString(radio.receiveString()); +}); +``` + +A simple program to send whether you are happy, or sad over ```radio```, using the A or B button to select an emotion. + +```blocks +let data: string = ""; +input.onButtonPressed(Button.A, () => { + radio.sendString("H"); +}); +input.onButtonPressed(Button.B, () => { + radio.sendString("S"); +}); +radio.onDataReceived(() => { + data = radio.receiveString(); + if ("H" == data) { + basic.showLeds(` + . . . . . + . # . # . + . . . . . + # . . . # + . # # # . + `); + } else if ("S" == data) { + basic.showLeds(` + . . . . . + . # . # . + . . . . . + . # # # . + # . . . # + `); + } else { + basic.showString("?"); + } +}); +``` + +### See also + +[send string](/reference/input/send-string), [on data received](/reference/radio/on-data-received) diff --git a/docs/reference/radio/send-string.md b/docs/reference/radio/send-string.md new file mode 100644 index 00000000..872c1d04 --- /dev/null +++ b/docs/reference/radio/send-string.md @@ -0,0 +1,33 @@ +# Send String + +Broadcasts a string data packet to other micro:bits connected via ``radio``. + +## Important Security Consideration + +The functions in the ``radio`` namespace allow the BBC micro:bit to communicate with other micro:bits. + +This API does not contain any form of encryption, authentication or authorization. It's purpose is solely for use as a teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + +For serious applications, BLE should be considered a substantially more secure alternative. + +```sig +radio.sendString("Hello world!") +``` + +### Parameters + +* msg - a string to be transmitted. + +### Examples + +Broadcasts the provided string to other micro:bits. + +```blocks +input.onButtonPressed(Button.A, () => { + radio.sendString("Mr. Watson, come here, I want to see you.") +}) +``` + +### See also + +[receive string](/reference/radio/receive-string), [on data received](/reference/radio/on-data-received) diff --git a/docs/reference/radio/set-transmit-power.md b/docs/reference/radio/set-transmit-power.md new file mode 100644 index 00000000..10c547dc --- /dev/null +++ b/docs/reference/radio/set-transmit-power.md @@ -0,0 +1,38 @@ +# Set Transmit Power + +Sets the transmitter power for ``radio`` communications. +The power can be set to a value between 0 (-30dbm) and 7 (+4dbm). + +## Range + +At power level 7, in an open area without significant interference (coming from WiFi networks or other devices operating on the 2.4 GHz range), you can get a **range of over 70m**. + +Indoors (or with additional interference), range will be significantly reduced. + +## Important Security Consideration + +The functions in the ``radio`` namespace allow the BBC micro:bit to communicate with other micro:bits. + +This API does not contain any form of encryption, authentication or authorization. It's purpose is solely for use as a teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + +For serious applications, BLE should be considered a substantially more secure alternative. + +```sig +radio.setTransmitPower(1) +``` + +### Parameters + +* ``power`` -- a [number](/reference/types/number) between ``0`` and ``7``. + +### Example + +Sets the transmitter power to full power at 7. + +```blocks +radio.setTransmitPower(7) +``` + +### See also + +[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received) diff --git a/docs/reference/radio/write-value-to-serial.md b/docs/reference/radio/write-value-to-serial.md new file mode 100644 index 00000000..a618b2b7 --- /dev/null +++ b/docs/reference/radio/write-value-to-serial.md @@ -0,0 +1,45 @@ +# Write Value To Serial + +Writes the full data received data via ``radio`` to serial in JSON format. +**Note** - This method only works for [send number](/reference/radio/send-number) and [send value](/reference/radio/send-value). It does not work for [send string](/reference/radio/send-string) (although a string can be sent with [send value](/reference/radio/send-value)). + +## Data received format +The format for received data printed to serial is as follows +- [send number](/reference/radio/send-number) - ```{v:ValueSent,t:MicrobitTimeAlive,s:Unused}``` +- [send value](/reference/radio/send-number) - ```{v:Value,t:MicrobitTimeAlive,s:Unused,n:"Name"}``` +- [send string](/reference/radio/send-string) - ```{}``` (currently unavailable) + +## Important Security Consideration + +The functions in the ``radio`` namespace allow the BBC micro:bit to communicate with other micro:bits. + +This API does not contain any form of encryption, authentication or authorization. It's purpose is solely for use as a teaching aid to demonstrate how simple communications operates, and to provide a sandpit through which learning can take place. + +For serious applications, BLE should be considered a substantially more secure alternative. + +```sig +radio.writeValueToSerial() +``` + +### Parameters + +* None + +### Examples + +When ```radio``` data is received (after pressing A button on 2nd micro:bit), output temperature data to serial. + +```blocks +input.onButtonPressed(Button.A, () => { + radio.sendNumber(input.temperature()); +}); +radio.onDataReceived(() => { + radio.writeValueToSerial(); +}); +``` +Example output to serial when A button pressed: +```{v:27,t:323,s:0}``` + +### See also + +[send number](/reference/radio/send-number), [send value](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)