c_meyer/pxt-calliope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update 'pins' ref pages (#1733)

Browse Source 
* Update 'pins' ref pages

* Some jsdoc touchups
This commit is contained in:
Galen Nickel
2019-01-03 16:02:19 -08:00
committed by Peli de Halleux
parent 7856c046f4
commit 079cd67c38
17 changed files with 214 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/reference/pins/i2c-read-buffer.md
View File

@ -8,11 +8,9 @@ pins.i2cReadBuffer(0, 0, false);
A device connected to the I2C pins on the @boardname@ at the address is selected to read data from. If it has data available to transfer, the data is received and copied into a buffer for your program to use. Your program says how big (how many bytes to receive) the buffer should be. You won't get back that many bytes of data if the connected device has less to send than what you asked for.
### ~hint
### ~ hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~

6
docs/reference/pins/i2c-read-number.md
View File

@ -6,11 +6,9 @@ Read one number from an I2C address using a specified number format.
pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
```
### ~hint
### ~ hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~

6
docs/reference/pins/i2c-write-buffer.md
View File

@ -8,11 +8,9 @@ pins.i2cWriteBuffer(0, null, false);
A device connected to the I2C pins on the @boardname@ at the address is selected to write data to. If the device is ready to take in your data, some or all of the data in your buffer is written to it.
### ~hint
### ~ hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~

6
docs/reference/pins/i2c-write-number.md
View File

@ -6,11 +6,9 @@ Write a number to a device at an I2C address using a specified number format.
pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
```
### ~hint
### ~ hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~

20
docs/reference/pins/on-pulsed.md
View File

@ -1,22 +1,26 @@
# On Pulsed
# on Pulsed
Configure the specified pin for digital input, and then
execute the associated code block whenever the pin
pulses **High** or **Low** (as specified).
Set a pin to use as a digital input and then run some code when the pin pulses either ``high`` or ``low``.
```sig
pins.onPulsed(DigitalPin.P0, PulseValue.High, () => { });
```
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``name``: The @boardname@ hardware pin to configure (``P0`` through ``P20``)
* ``pulse``: Which state will cause the associated block to execute (**High** or **Low**)
* **name**: the @boardname@ hardware pin to set for digital input (``P0`` through ``P20``).
* **pulse**: the state that will cause the code inside the block to run, either ``high`` or ``low``.
* **body**: the code to run when the pin in **name** is pulsed to the state set in **pulse**.
## Example
The following example configures pin ``P2`` for digital input,
and then displays the string `LOW` whenever ``P2`` pulses low.
Configure pin ``P2`` for digital input. Display the string `"LOW"` whenever ``P2`` pulses ``low``.
```blocks
pins.onPulsed(DigitalPin.P2, PulseValue.Low, () => {

19
docs/reference/pins/pulse-duration.md
View File

@ -1,21 +1,26 @@
# Pulse Duration
# pulse Duration
Gets the duration of the last pulse in microseconds.
This function should be called from an **on pulsed** handler.
Get the duration of the last pulse in microseconds.
```sig
pins.pulseDuration();
```
A pin pulse is detected in the [onPulsed](/reference/pins/on-pulsed) event. You use **pulseDuration** inside that event to get the duration of the pulse that triggered the event.
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Returns
The duration of the last pulse, measured in microseconds.
* a [number](/types/number) that is the duration of the last pulse, measured in microseconds.
## Example
The following example waits for pin ``P0`` to be pulsed high, and then
displays the duration of the pulse in microseconds on the LED screen.
Wait for pin ``P0`` to be pulsed high. Display the duration of the pulse in microseconds on the LED screen.
```blocks
pins.onPulsed(DigitalPin.P0, PulseValue.High, () => {

29
docs/reference/pins/pulse-in.md
View File

@ -1,7 +1,6 @@
# Pulse In
# pulse In
Returns the duration of a pulse (high or low) from a [pin](/device/pins) on
the @boardname@ board in microseconds.
Get the duration, in microseconds, of a pulse (high or low) from one of the pins.
```sig
pins.pulseIn(DigitalPin.P0, PulseValue.High)
@ -14,19 +13,25 @@ Please read the [page about pins](/device/pins) carefully.
## ~
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``name`` is a [string](/types/string) that stores the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``)
* ``value`` is the value of the pulse, ``high`` or ``low``
* ``maxDuration``, maximum duration in micro-seconds. If no pulse is received
* ``name`` the name of the pin (``P0``, ``P1``, or ``P2``, up through ``P20``).
* ``value`` the value of the pulse, either ``high`` or ``low``.
* ``maxDuration``, maximum duration to wait for the pulse in microseconds. If no pulse is received, the duration returned is `0`.
## Returns
* a [number](/types/number) that represents the pulse duration in micro-seconds
* a [number](/types/number) that is the pulse duration in microseconds.
## Example: Measuring distance with a sonar
The following script sends a pulse on ``P0`` and reads the pulse returned by a HC-SR04 sonar to determine the distance of the object in front of the sensor.
Send a pulse on ``P0`` and read a pulse returned by a HC-SR04 sonar ultrasonic sensor. The sensor determines the distance of the object in front of it.
```blocks
basic.forever(() => {
@ -43,12 +48,6 @@ basic.forever(() => {
})
```
### ~hint
This function is not supported in the simulator.
### ~
## See also
[digital write pin](/reference/pins/digital-write-pin),
[digital write pin](/reference/pins/digital-write-pin)

11
docs/reference/pins/set-events.md
View File

@ -1,4 +1,4 @@
# Set Events
# set Events
Configure the type of events emitted by a given pin.
@ -6,6 +6,12 @@ Configure the type of events emitted by a given pin.
pins.setEvents(DigitalPin.P0, PinEventType.Edge);
```
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``name``: The @boardname@ hardware pin to configure (``P0`` through ``P20``)
@ -13,8 +19,7 @@ pins.setEvents(DigitalPin.P0, PinEventType.Edge);
## Example
The following example configures pin ``P0`` and then
subscribes to the rise and fall events.
The following example configures pin ``P0`` and then subscribes to the rise and fall events.
```blocks
control.onEvent(control.eventSourceId(EventBusSource.MICROBIT_ID_IO_P0), control.eventValueId(EventBusValue.MICROBIT_PIN_EVT_RISE), () => {

37
docs/reference/pins/spi-format.md
View File

@ -1,16 +1,43 @@
# SPI Format
# spi Format
Sets the SPI format
Set the Serial Peripheral Interface (SPI) format.
```sig
pins.spiFormat(8, 3);
```
The data sent over a SPI connection has a number of _bits_ to represent each value. Also, position of the clock signal (SCK), ``high`` or ``low``, and the exact time when a data value is read is determined by the SPI _mode_. Both the bits and mode values together are called the _SPI format_.
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
The default number of bits is `8` and the default mode value is `3`.
## Parameters
* ``bits``,
* ``mode``,
* **bits**: the [number](types/number) of bits for each data value sent and received on the SPI connection. This value must be ``8`` since only 8 bits is currently supported for SPI data values.
* **mode**: a [number](/types/number) that is the mode value for the SPI clock (**SCK**) signalling. The different modes are:
>* `0`: the data line is active when **SCK** goes to ``high`` and the data values are read when **SCK** goes to ``high``
>* `1`: the data line is active when **SCK** goes to ``high`` and the data values are read when **SCK** goes to ``low``
>* `2`: the data line is active when **SCK** goes to ``low`` and the data values are read when **SCK** goes to ``high``
>* `3`: the data line is active when **SCK** goes to ``low`` and the data values are read when **SCK** goes to ``low``
## Example
Set the pins and format for the SPI connection.
```blocks
pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
pins.spiFormat(8, 3);
```
## See also
[SPI](https://developer.mbed.org/handbook/SPI)
[spi write](/reference/pins/spi-write),
[spi pins](/reference/pins/spi-pins),
[spi frequency](/reference/pins/spi-frequency)
[SPI Programming](https://developer.mbed.org/handbook/SPI)

22
docs/reference/pins/spi-frequency.md
View File

@ -1,18 +1,28 @@
# SPI Frequency
# spi Frequency
Set the SPI clock frequency.
Set the Serial Peripheral Interface (SPI) clock frequency.
```sig
pins.spiFrequency(1000000);
```
The @boardname@ sets the rate of data transfer and control timing for a SPI connection. This data rate and timing signal is controlled by the **SCK** pin. The signal on this pin is _clocked_ using the frequency set for it.
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
The default clock frequency is 1 Mhz (10000000 Hz). You can set the frequency for the SPI connection to some other value if you need a different data rate.
## Parameters
* **frequency**: a [number](/types/number) to set as the frequency for SPI bus clock. This value is the number of clock changes per second (Hz).
## Example
Read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **13**, **14**, and **15**.
Read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **P13**, **P14**, and **P15**.
```blocks
pins.digitalWritePin(DigitalPin.P0, 1);
@ -29,4 +39,8 @@ serial.writeLine("WHOAMI register value: " + whoami)
## See also
[SPI](https://developer.mbed.org/handbook/SPI)
[spi write](/reference/pins/spi-write),
[spi pins](/reference/pins/spi-pins),
[spi format](/reference/pins/spi-format)
[SPI Programming](https://developer.mbed.org/handbook/SPI)

38
docs/reference/pins/spi-pins.md
View File

@ -1,17 +1,43 @@
# SPI Pins
# spi Pins
Sets the SPI MOSI, MISO and SCK pins
Set the Serial Peripheral Interface (SPI) signalling pins
```sig
pins.spiPins(DigitalPin.P0, DigitalPin.P1, DigitalPin.P2);
```
To configure the @boardname@ to write to an external device using a SPI connection, each SPI signal line is assigned to unique a pin. A SPI connection uses 3 signalling lines called **MOSI**, **MISO**, and **SCK**.
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
If you don't set the pins for the SPI connection, the default pin assignments are used:
* **P15** = **MOSI**, @boardname@ SPI data output pin
* **P14** = **MISO**, @boardname@ SPI data input pin
* **P13** = **SCK**, @boardname@ SPI serial clock output pin
## Parameters
* ``MOSI``, the ``MOSI`` pin
* ``MISO``, the ``MISO`` pin
* ``SCK``, the ``SCK`` pin
* **mosi**: the pin for SPI data output, the **MOSI** signal pin.
* **miso**: the pin for SPI data input, the **MISO** signal pin.
* **sck**: the pin for SPI serial clock output, the **SCK** signal pin.
## Example
Set the pin assignments for a SPI connection to the default pins.
```blocks
pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
```
## See also
[SPI](https://developer.mbed.org/handbook/SPI)
[spi write](/reference/pins/spi-write),
[spi frequency](/reference/pins/spi-frequency),
[spi format](/reference/pins/spi-format)
[SPI Programming](https://developer.mbed.org/handbook/SPI)

39
docs/reference/pins/spi-write.md
View File

@ -1,19 +1,48 @@
# SPI Write
# spi Write
Write to the SPI Slave and return the response.
Write a data value to the SPI slave device and return its response.
```sig
pins.spiWrite(0);
```
Data values are written to a SPI slave device connected to the @boardname@ by the [SPI pins](/reference/pins/spi-pins). The data value might be either a command for the connected device or some value for its use. If the write operation causes the connected device to send a value back to the @boardname@, this will be the return value for the **spiWrite** function.
### ~ hint
**Simulator**: This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``value``: value Data to be sent to the SPI slave
* ``value``: a [number](/types/number) which is the data value to send to the SPI slave device.
## Returns
* a [number](/types/number) Response from the SPI slave
* a [number](/types/number) value which is the response from the SPI slave device.
## Example
Send the command to read the value of the _WHOAMI_ register from the device connected to the SPI bus. The chip select line is connected to pin **0** and the SPI signals use pins **P13**, **P14**, and **P15**.
```blocks
pins.digitalWritePin(DigitalPin.P0, 1);
pins.spiPins(DigitalPin.P15, DigitalPin.P14, DigitalPin.P13);
pins.spiFormat(8, 3);
pins.spiFrequency(1000000);
pins.digitalWritePin(DigitalPin.P0, 0);
let command = pins.spiWrite(143);
let whoami = pins.spiWrite(0);
pins.digitalWritePin(DigitalPin.P0, 1);
basic.showNumber(whoami);
serial.writeLine("WHOAMI register value: " + whoami)
```
## See also
[SPI](https://developer.mbed.org/handbook/SPI)
[spi pins](/reference/pins/spi-pins),
[spi frequency](/reference/pins/spi-frequency),
[spi format](/reference/pins/spi-format)
[SPI Programming](https://developer.mbed.org/handbook/SPI)