Merge branch 'master' of https://github.com/Microsoft/pxt-microbit

docs/projects/rock-paper-scissors.md

@@ -55,7 +55,8 @@ input.onGesture(Gesture.Shake, () => {
 ```
 
 Next, when you shake the micro:bit, it should pick a random number from `0` to `2`
-and store it in the variable.
+and store it in the variable `weapon`. (This variable is named `weapon` because 
+rock, paper, and scissors are the weapons you use to battle your friends!)
 
 Add a ``set`` block with a variable. Then add a ``pick random`` block,
 and store the random number in the variable,
@@ -230,4 +231,4 @@ input.onButtonPressed(Button.B, () => {
 ## Step 8: Hacking Rock Paper Scissors
 
 How else can you make your game better?
-Ever hear of [Rock Paper Scissors Spock Lizard](https://en.wikipedia.org/wiki/Rock-paper-scissors#Additional_weapons)?
+Ever hear of [Rock Paper Scissors Spock Lizard](http://www.samkass.com/theories/RPSSL.html)?

docs/reference/radio/on-data-received.md

@@ -2,18 +2,6 @@
 
 Registers code to run when a packet is received over ``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.onDataReceived(() => {})
-```
-
 ### Parameters
 
 * body - is an action

docs/reference/radio/receive-number.md

@@ -1,26 +1,15 @@
 # Receive Number
 
-Reads the next radio packet if any and returns the first number.
+Receives the next number sent by a micro:bit in the same ``radio`` group.
-
-## 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.receiveNumber()
-```
 
 ### Return value
 
-* the first number [number](/reference/types/number) of the packet if any. `0` otherwise.
+* the first  [number](/reference/types/number) that the micro:bit received. If it did not receive any numbers, this function will return `0`.
 
-### Examples
+### Example: Simple number receiver
 
-Read the number broadcasted by other micro:bits.
+This example receives the number broadcasted another micro:bit and shows it
+as a bar graph.
 
 ```blocks
 radio.onDataReceived(() => {
@@ -28,7 +17,42 @@ radio.onDataReceived(() => {
 })
 ```
 
+### Example: Light level receiver 
+
+This example shows the light level from the [light level sender example](/reference/input/send-number)
+as a number.
+
+```blocks
+radio.setGroup(99)
+basic.forever(() => {
+    let level = radio.receiveNumber()
+    basic.showNumber(level)
+})
+```
+
+### Example: Mailbot
+
+This example receives the light level from the [light level sender example](/reference/input/send-number)
+and shows a text string like **ALERT** if the light level becomes much brighter.
+To find when the mail arrives, you can put the light level sender in your mailbox and it will
+tell you when someone opens the box. You can try this with a normal
+box too, like a present for a friend.
+
+```blocks
+radio.setGroup(99)
+let max = 0
+basic.forever(() => {
+    let level = radio.receiveNumber()
+    if (level > max) {
+        max = level
+    }
+    if (max > 10) {
+        basic.showString("ALERT")
+    }
+})
+```
+
 ### See also
 
-[receive number](/reference/input/receive-number), [on data received](/reference/radio/on-data-received)
+[send number](/reference/input/send-number), [on data received](/reference/radio/on-data-received)
 

docs/reference/radio/send-number.md

@@ -1,26 +1,16 @@
 # Send Number
 
-Broadcasts a number data packet to other micro:bits connected via ``radio``.
+Broadcast a number 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.sendNumber(0)
-```
 
 ### Parameters
 
-* packet - a number to be transmitted.
+* num - a number to send.
 
-### Examples
+### Example: Broadcasting acceleration
 
-Broadcasts the value of ``acceleration`` x to other micro:bits.
+This example broadcasts the value of your micro:bit's ``acceleration`` in the `x` direction 
+(left and right) to other micro:bits.
+This kind of program might be useful in a model car or model rocket.
 
 ```blocks
 input.onButtonPressed(Button.A, () => {
@@ -30,7 +20,9 @@ input.onButtonPressed(Button.A, () => {
 
 ### Light level sender
 
-This example broadcasts the level of the light around it:
+This example broadcasts the level of the light around it.
+You can do some interesting things with it if you use it along with the
+[Mailbot](/reference/radio/receive-number) example.
 
 ```blocks
 radio.setGroup(99)
@@ -40,38 +32,6 @@ basic.forever(() => {
 })
 ```
 
-This example shows the light level from the sender (above):
-
-```blocks
-radio.setGroup(99)
-basic.forever(() => {
-    let level = radio.receiveNumber()
-    basic.showNumber(level)
-})
-```
-
-### Mailbot
-
-This example takes the signal from the light level sender (above)
-and shows a text string if the light level becomes much brighter.
-You can put the light level sender in your mailbox and it will
-tell you when someone opens the box. You can try this with a normal
-box too, like a present.
-
-```blocks
-radio.setGroup(99)
-let max = 0
-basic.forever(() => {
-    let level = radio.receiveNumber()
-    if (level > max) {
-        let max = level
-    }
-    if (max > 10) {
-        basic.showString("ALERT")
-    }
-})
-```
-
 ### See also
 
 [receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)

docs/reference/radio/set-group.md

@@ -4,18 +4,6 @@ Sets the group id for ``radio`` communications. A micro:bit can only listen to o
 
 Unless specified, the group id is automatically inferred from the script source. Every script with the same exact source code with start with the same group id.
 
-## 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.setGroup(1)
-```
-
 ### Parameters
 
 * ``id`` -- a [number](/reference/types/number) between ``0`` and ``255``.