Deprecating old radio APIs and fixing docs (#289)

This commit is contained in:
Richard Knoll 2016-10-24 16:30:21 -07:00 committed by Peli de Halleux
parent ba69563bf4
commit ec404e5887
25 changed files with 205 additions and 163 deletions

View File

@ -22,9 +22,8 @@ Learn the functions of **on data received**, **send number** and **receive numbe
input.acceleration(Dimension.X)
led.plotBarGraph(0, 1023)
basic.showNumber(0)
radio.onDataReceived(() => {})
radio.onDataPacketReceived(() => {})
radio.sendNumber(0)
radio.receiveNumber()
```
## Objectives

View File

@ -28,7 +28,7 @@ We want to register code to run when a packet is received over radio. We can imp
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X))
})
radio.onDataReceived(() => {
radio.onDataPacketReceived(() => {
})
```
@ -39,8 +39,8 @@ Finally, we want to chart the acceleration. So we must first implement `plot bar
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X))
})
radio.onDataReceived(() => {
led.plotBarGraph(radio.receiveNumber(), 1023)
radio.onDataPacketReceived(({ receivedNumber }) => {
led.plotBarGraph(receivedNumber, 1023)
})
```

View File

@ -19,7 +19,6 @@ Learn how to use running time. We will be learning how to create a pogo game usi
let jumps = 0
let acc = input.acceleration(Dimension.Y)
basic.showNumber(0)
radio.receiveNumber()
led.stopAnimation()
radio.sendNumber(0)
basic.forever(() => { })
@ -32,7 +31,7 @@ basic.showLeds(`
`)
basic.clearScreen()
if (true) {}
radio.onDataReceived(() => { })
radio.onDataPacketReceived(() => { })
```
## Objectives

View File

@ -120,8 +120,8 @@ input.onButtonPressed(Button.AB, () => {
let jumps = 0
basic.showNumber(jumps)
})
radio.onDataReceived(() => {
basic.showNumber(radio.receiveNumber())
radio.onDataPacketReceived(({ receivedNumber }) => {
basic.showNumber(receivedNumber)
})
```
@ -151,8 +151,8 @@ input.onButtonPressed(Button.AB, () => {
let jumps = 0
basic.showNumber(jumps)
})
radio.onDataReceived(() => {
basic.showNumber(radio.receiveNumber())
radio.onDataPacketReceived(({ receivedNumber }) => {
basic.showNumber(receivedNumber)
led.stopAnimation()
})

View File

@ -21,9 +21,8 @@ Learn how to **show LEDs** to turn on a LED light pattern on the LED screen. We
basic.forever(() => {});
radio.sendNumber(0);
input.acceleration(Dimension.Strength)
radio.onDataReceived(() => {});
radio.onDataPacketReceived(() => {});
led.plotBarGraph(0, 0);
radio.receiveNumber();
```
## Objectives

View File

@ -78,7 +78,7 @@ Your finished code will look like this:
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.Strength) - 1023);
});
radio.onDataReceived(() => {
radio.onDataPacketReceived(() => {
});
```
@ -92,8 +92,8 @@ Your finished code will look like this:
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.Strength) - 1023);
});
radio.onDataReceived(() => {
led.plotBarGraph(radio.receiveNumber(), 0);
radio.onDataPacketReceived(({ receivedNumber }) => {
led.plotBarGraph(receivedNumber, 0);
});
```

View File

@ -16,13 +16,13 @@ input.onButtonPressed(Button.A, () => {
## Step 2
Use [radio on data received](/reference/radio/on-data-received) display "YO" when the number ``0`` is received
Use [radio on data packet received](/reference/radio/on-data-packet-received) display "YO" when the number ``0`` is received
by radio.
```blocks
let message = 0;
radio.onDataReceived(() => {
message = radio.receiveNumber();
radio.onDataPacketReceived(({ receivedNumber }) => {
message = receivedNumber;
if (message == 0) {
basic.showString("YO")
}
@ -43,13 +43,13 @@ input.onButtonPressed(Button.B, () => {
## Step 4
Add blocks in [radio on data received](/reference/radio/on-data-received) to display "BYE" when the number ``1`` is received
Add blocks in [radio on data packet received](/reference/radio/on-data-packet-received) to display "BYE" when the number ``1`` is received
by radio.
```blocks
let message = 0;
radio.onDataReceived(() => {
message = radio.receiveNumber();
radio.onDataPacketReceived(({ receivedNumber }) => {
message = receivedNumber;
if (message == 0) {
basic.showString("YO")
}

View File

@ -28,7 +28,7 @@ We want to register code to run when a packet is received over radio. We can imp
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X))
})
radio.onDataReceived(() => {
radio.onDataPacketReceived(() => {
})
```
@ -39,8 +39,8 @@ Finally, we want to chart the acceleration. So we must first implement `plot bar
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X))
})
radio.onDataReceived(() => {
led.plotBarGraph(radio.receiveNumber(), 1023)
radio.onDataPacketReceived(({ receivedNumber }) => {
led.plotBarGraph(receivedNumber, 1023)
})
```

View File

@ -6,13 +6,9 @@ Communicate data using radio packets
radio.sendNumber(0);
radio.sendValue("data", 0);
radio.sendString("");
radio.onDataReceived(() => {
radio.onDataPacketReceived(() => {
});
radio.receiveNumber();
radio.receivedNumberAt(0);
radio.receiveString();
radio.receivedSignalStrength();
radio.setGroup(0);
radio.setTransmitPower(7);
radio.setTransmitSerialNumber(false);
@ -25,4 +21,11 @@ radio
### See Also
[sendNumber](/reference/radio/send-number), [sendValue](/reference/radio/send-value), [sendString](/reference/radio/send-string), [onDataReceived](/reference/radio/on-data-received), [receiveNumber](/reference/radio/receive-number), [receiveString](/reference/radio/receive-string), [receivedSignalStrength](/reference/radio/received-signal-strength), [setGroup](/reference/radio/set-group), [setTransmitPower](/reference/radio/set-transmit-power), [setTransmitSerialNumber](/reference/radio/set-transmit-serial-number), [writeValueToSerial](/reference/radio/write-value-to-serial)
[sendNumber](/reference/radio/send-number),
[sendValue](/reference/radio/send-value),
[sendString](/reference/radio/send-string),
[onDataPacketReceived](/reference/radio/on-data-packet-received),
[setGroup](/reference/radio/set-group),
[setTransmitPower](/reference/radio/set-transmit-power),
[setTransmitSerialNumber](/reference/radio/set-transmit-serial-number),
[writeValueToSerial](/reference/radio/write-value-to-serial)

View File

@ -0,0 +1,40 @@
# On Data Packet Received
Run part of a program when the micro:bit receives a
[number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
```sig
radio.onDataPacketReceived((packet: Packet) => { });
```
### Callback Parameters
* ``packet`` - the [packet](/reference/radio/packet) that was received by the radio
### Example
This program keeps sending numbers that says how fast the micro:bit is
slowing down or speeding up. It also receives numbers for the same
thing from nearby micro:bits. It shows these numbers as a
[bar graph](/reference/led/plot-bar-graph).
```blocks
basic.forever(() => {
radio.sendNumber(input.acceleration(Dimension.X));
})
radio.onDataPacketReceived(({ receivedNumber }) => {
led.plotBarGraph(receivedNumber, 1023);
})
```
### See also
[send number](/reference/radio/send-number),
[send string](/reference/radio/send-string),
[send value](/reference/radio/send-value),
[set group](/reference/radio/set-group)
```package
radio
```

View File

@ -1,5 +1,7 @@
# On Data Received
> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
Run part of a program when the micro:bit receives a
[number](/reference/types/number) or [string](/reference/types/string) over ``radio``.
@ -8,10 +10,6 @@ Run part of a program when the micro:bit receives a
radio.onDataReceived(() => { });
```
### Simulator
This function only works on the micro:bit, not in browsers.
### Example
This program keeps sending numbers that says how fast the micro:bit is
@ -30,7 +28,7 @@ radio.onDataReceived(() => {
### See also
[receive number](/reference/radio/receive-number),
[on data packet received](/reference/radio/on-data-packet-received),
[send number](/reference/radio/send-number), [set group](/reference/radio/set-group)
```package

View File

@ -0,0 +1,19 @@
# Packet
A packet that was received by the radio.
## Properties
* `receivedNumber` - The number that was sent in this packet or `0` if this packet did not contain a number. See [send number](/reference/radio/send-number) and [send value](/reference/radio/send-value)
* `text` - The string that was sent in this packet or the empty string if this packet did not contain a string. See [send string](/reference/radio/send-string) and [send value](/reference/radio/send-value)
* `time` - The system time of the micro:bit that sent this packet at the time the packet was sent.
* `serial` - The serial number of the micro:bit that sent this packet or `0` if the micro:bit did not include its serial number.
* `signal` - How strong the radio signal is from `255` (weak) to `0` (strong).
### See also
[on data packet received](/reference/radio/on-data-packet-received),
```package
radio
```

View File

@ -1,5 +1,7 @@
# Receive Number
> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
Receives the next number sent by a micro:bit in the same ``radio`` group.
```sig
@ -10,10 +12,6 @@ radio.receiveNumber();
* the first [number](/reference/types/number) that the micro:bit received. If it did not receive any numbers, this function will return `0`.
### Simulator
This function only works on the micro:bit, not in browsers.
### Example: Simple number receiver
This example receives the number broadcasted another micro:bit and shows it

View File

@ -1,5 +1,7 @@
# Receive String
> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
Find the next string sent by `radio` from another micro:bit.
```sig
@ -11,10 +13,6 @@ radio.receiveString()
* the first [string](/reference/types/string) that was sent. If no
string was sent, then this function returns an empty (blank) string.
### Simulator
This function only works on the micro:bit, not in browsers.
### Example: Simple receiver
Show the string sent by another micro:bit.

View File

@ -1,11 +1,13 @@
# Received Signal Strength
> Note: This API has been deprecated! Use [on data packet received](/reference/radio/on-data-packet-received) instead.
Find how strong the ``radio`` signal is, from `255` to `0`.
(`255` means a weak signal and `0` means a strong one.)
The micro:bit finds the signal strength by checking how strong it was
the last time it ran the
[receive number](/reference/radio/receive-number) function. That means
[on data packet received](/reference/radio/on-data-packet-received) function. That means
it needs to run **receive number** first.
```sig
@ -37,7 +39,7 @@ basic.forever(() => {
### See also
[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
```package
radio

View File

@ -10,9 +10,6 @@ radio.sendNumber(0);
* ``value`` - a [number](/reference/types/number) to send.
### Simulator
This function only works on the micro:bit, not in browsers.
### Example: Broadcasting acceleration
@ -30,7 +27,7 @@ input.onButtonPressed(Button.A, () => {
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.
[on data packet received](/reference/radio/on-data-packet-received) example.
```blocks
radio.setGroup(99)
@ -42,7 +39,7 @@ basic.forever(() => {
### See also
[receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received)
```package
radio

View File

@ -1,6 +1,7 @@
# Send String
Sends a string to other micro:bits in the area connected by radio.
Sends a string to other micro:bits in the area connected by radio. The
maximum string length is 19 characters.
```sig
radio.sendString("Hello!")
@ -10,9 +11,6 @@ radio.sendString("Hello!")
* `msg` is a [string](/reference/types/string) to send by radio.
### Simulator
This function only works on the micro:bit, not in browsers.
### Example: Two-way radio
@ -26,8 +24,8 @@ input.onButtonPressed(Button.A, () => {
basic.showString("SENT");
})
radio.onDataReceived(() => {
basic.showString(radio.receiveString());
radio.onDataPacketReceived(({ text }) => {
basic.showString(text);
});
```
@ -39,7 +37,7 @@ A radio that can both transmit and receive is called a _transceiver_.
### See also
[receive string](/reference/radio/receive-string), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received)
```package
radio

View File

@ -1,6 +1,7 @@
# Send Value
Send a [string]() and [number]() together by ``radio`` to other micro:bits.
The maximum [string]() length is 12 characters.
```sig
radio.sendValue("data", 0);
@ -11,10 +12,6 @@ radio.sendValue("data", 0);
* ``name`` is a [string](/reference/types/string) to send by radio
* ``value`` a [number](/reference/types/number) to send by radio
### Simulator
This function only works on the micro:bit, not in browsers.
### Example: Broadcasting acceleration
This program sends your micro:bit's **acceleration** (amount it is
@ -34,15 +31,15 @@ Then it shows them on the LED screen.
```blocks
radio.setGroup(99)
radio.onDataReceived(() => {
basic.showString(radio.receiveString());
basic.showNumber(radio.receiveNumber());
radio.onDataPacketReceived(({ text, receivedNumber }) => {
basic.showString(text);
basic.showNumber(receivedNumber);
});
```
### See also
[receive number](/reference/radio/receive-number), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received)
```package
radio

View File

@ -32,7 +32,10 @@ radio.setGroup(128)
### See also
[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)
```package
radio

View File

@ -37,7 +37,10 @@ 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)
[on data packet received](/reference/radio/on-data-packet-received),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)
```package
radio

View File

@ -10,10 +10,6 @@ radio.setTransmitSerialNumber(true);
* ``transmit`` is a [boolean](/reference/types/boolean) that represents whether the serial number needs to be transmitted.
### Simulator
This function only works on the micro:bit, not in browsers.
### Example
This program makes the ``radio`` send the serial number in each packet.
@ -24,7 +20,10 @@ radio.setTransmitSerialNumber(true);
### See also
[receive number](/reference/radio/receive-number), [send number](/reference/radio/send-number), [on data received](/reference/radio/on-data-received)
[on data packet received](/reference/radio/on-data-packet-received),
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[send string](/reference/radio/send-string)
```package
radio

View File

@ -6,25 +6,13 @@ Writes the data received by ``radio`` to serial in JSON format.
radio.writeValueToSerial();
```
### ~hint
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 you can send a
string as part of [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-value): ```{v:ValueSent,t:MicrobitTimeAlive,s:Unused,n:"Name"}```
### Simulator
This function only works on the micro:bit, not in browsers.
- [send number](/reference/radio/send-number): ```{v:ValueSent,t:MicrobitTimeAlive,s:SerialNumber}```
- [send value](/reference/radio/send-value): ```{v:ValueSent,t:MicrobitTimeAlive,s:SerialNumber,n:"Name"}```
- [send string](/reference/radio/send-string): ```{t:MicrobitTimeAlive,s:SerialNumber,n:"Text"}```
### Examples
@ -50,7 +38,8 @@ Sample output to serial when ``A`` button pressed:
[send number](/reference/radio/send-number),
[send value](/reference/radio/send-value),
[on data received](/reference/radio/on-data-received)
[send string](/reference/radio/send-string),
[on data packet received](/reference/radio/on-data-packet-received)
```package
radio

View File

@ -244,7 +244,7 @@ namespace radio {
//% help=radio/receive-number
//% weight=46
//% blockId=radio_datagram_receive block="radio receive number" blockGap=8
//% advanced=true
//% deprecated=true
int receiveNumber()
{
if (radioEnable() != MICROBIT_OK) return 0;
@ -258,7 +258,7 @@ namespace radio {
//% help=radio/on-data-received
//% weight=50
//% blockId=radio_datagram_received_event block="radio on data received" blockGap=8
//% advanced=true
//% deprecated=true
void onDataReceived(Action body) {
if (radioEnable() != MICROBIT_OK) return;
registerWithDal(MICROBIT_ID_RADIO, MICROBIT_RADIO_EVT_DATAGRAM, body);
@ -274,7 +274,7 @@ namespace radio {
//% blockId=radio_datagram_receive_string block="radio receive string" blockGap=8
//% weight=44
//% help=radio/receive-string
//% advanced=true
//% deprecated=true
StringData* receiveString() {
if (radioEnable() != MICROBIT_OK) return ManagedString().leakData();
receivePacket(false);
@ -289,7 +289,7 @@ namespace radio {
//% help=radio/received-signal-strength
//% weight=40
//% blockId=radio_datagram_rssi block="radio received signal strength"
//% advanced=true
//% deprecated=true
int receivedSignalStrength() {
if (radioEnable() != MICROBIT_OK) return 0;
return packet.getRSSI();

View File

@ -32,6 +32,7 @@ namespace radio {
* Registers code to run when the radio receives a packet. Also takes the
* received packet from the radio queue.
*/
//% help=radio/on-data-packet-received
//% mutate=true
//% mutateText=Packet
//% mutateDefaults="receivedNumber;text,receivedNumber;text"

View File

@ -50,7 +50,7 @@ declare namespace radio {
//% help=radio/receive-number
//% weight=46
//% blockId=radio_datagram_receive block="radio receive number" blockGap=8
//% advanced=true shim=radio::receiveNumber
//% deprecated=true shim=radio::receiveNumber
function receiveNumber(): number;
/**
@ -59,7 +59,7 @@ declare namespace radio {
//% help=radio/on-data-received
//% weight=50
//% blockId=radio_datagram_received_event block="radio on data received" blockGap=8
//% advanced=true shim=radio::onDataReceived
//% deprecated=true shim=radio::onDataReceived
function onDataReceived(body: () => void): void;
/**
@ -69,7 +69,7 @@ declare namespace radio {
//% blockId=radio_datagram_receive_string block="radio receive string" blockGap=8
//% weight=44
//% help=radio/receive-string
//% advanced=true shim=radio::receiveString
//% deprecated=true shim=radio::receiveString
function receiveString(): string;
/**
@ -80,7 +80,7 @@ declare namespace radio {
//% help=radio/received-signal-strength
//% weight=40
//% blockId=radio_datagram_rssi block="radio received signal strength"
//% advanced=true shim=radio::receivedSignalStrength
//% deprecated=true shim=radio::receivedSignalStrength
function receivedSignalStrength(): number;
/**