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

Add and update I2C topics (#602)

Browse Source 
* Add and update I2C topics

* Throw in some edits for the serial buffer apis

* Add an example to serial read buffer
This commit is contained in:
Galen Nickel 2017-12-11 22:34:33 -08:00 committed by Peli de Halleux
parent f2f097a9ed
commit 985ad3d8e3
8 changed files with 165 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/reference/pins/i2c-read-buffer.md Normal file
View File

@ -0,0 +1,42 @@
# i2c Read Buffer
Read data into a buffer from a device at an I2C address.
```sig
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
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* **address**: the 7-bit I2C address to read the data from.
* **size**: the [number](/types/number) of bytes to read into the buffer from the device.
* **repeated**: if `true`, a [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure the data is read from the device with out an interruption. If set to `false` (the default), the data is read without setting a start condition more than once.
## Returns
* a [buffer](/types/buffer) that contains the data read from the device at the I2C address. The number of bytes returned to you is less than or equal to amount you asked for in the **size** parameter.
## Example
Tell a device connected to the I2C pins with the address of `141` to respond to a _read status_ command. The device sends the status data on the I2C wires if receives a command byte equal to `0`. `32` bytes of status data are read into a buffer.
```blocks
const i2cDevice = 141;
pins.i2cWriteNumber(i2cDevice, NumberFormat.UInt8LE, 0)
let i2cBuffer = pins.i2cReadBuffer(i2cDevice, 32, false);
```
## See also
[i2c write buffer](/reference/pins/i2c-write-buffer), [buffer](/types/buffer)
[What's I2C?](http://www.i2c-bus.org/)

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

@ -1,39 +1,40 @@
# I2C Read Number
Read one number from the specified 7-bit I2C address, in the specified
number format.
Read one number from an I2C address using a specified number format.
```sig
pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
```
### ~hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``address``: the 7-bit I2C address from which to read the number.
* ``format``: the number format. Formats include
**Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
**Int8BE**, **UInt8BE**, **Int16BE**, **UInt16BE**, and
**Int32BE**.
* **Int** stands for "integer", and **UInt** stands for "unsigned integer".
* **LE** stands for "little-endian" and **BE** stands for "big-endian".
* The number in each format name stands for the number of bits in the format.
* ``repeated`` repeated start, true - don't send stop at end
* **address**: the 7-bit I2C address of the device you want to read a number from.
* **format**: the [NumberFormat](/types/buffer/number-format) of the number value to read.
* **repeated**: repeated start, true - don't send stop at end.
* **repeated**: if `true`, a [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure the number is read from the device with out an interruption. If set to `false` (the default), the number is read without setting a start condition more than once.
## Returns
* a number from the device with the [NumberFormat](/types/buffer/number-format) you asked for.
## Example
The following example reads a number in big-endian, 16-bit, unsigned integer
format from the 7-bit I2C address `32`.
Read a number from the device at a 7-bit I2C address as a 16-bit number. The `16`, big-endian, and integer chosen for the format.
```blocks
pins.i2cReadNumber(32, NumberFormat.UInt16BE, false);
```
### ~hint
This function is not supported in the simulator.
### ~
## See also
[I2C](https://en.wikipedia.org/wiki/I%C2%B2C)
[What's I2C?](http://www.i2c-bus.org/), [number format](/types/buffer/number-format)

42
docs/reference/pins/i2c-write-buffer.md Normal file
View File

@ -0,0 +1,42 @@
# i2c Write Buffer
Write data from buffer to a device at an I2C address.
```sig
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
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* **address**: the 7-bit I2C address to read the data from.
* **buffer**: a [buffer](/types/buffer) that contains the data to write to the device at the I2C address.
* **repeated**: if `true`, a [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure the data is written to the device with out an interruption. If set to `false` (the default), the data is written without setting a start condition more than once.
## Example
Tell a device connected to the I2C pins with the address of `141` to respond to a _read status_ command. The device sends the status data on the I2C wires if receives a command byte equal to `0`. `32` bytes of status data is read into a buffer.
The third byte is changed and the buffer is sent back to have the device update its status.
```blocks
const i2cDevice = 141;
pins.i2cWriteNumber(i2cDevice, NumberFormat.UInt8LE, 0)
let i2cBuffer = pins.i2cReadBuffer(i2cDevice, 32, false);
i2cBuffer.setNumber(NumberFormat.UInt8LE, 2, 0)
pins.i2cWriteBuffer(i2cDevice, i2cBuffer, false)
```
## See also
[i2c read buffer](/reference/pins/i2c-read-buffer), [buffer](/types/buffer)
[What's I2C?](http://www.i2c-bus.org/)

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

@ -1,40 +1,33 @@
# I2C Write Number
# i2c Write Number
Write the specified number to the specified 7-bit I2C address in the
specified number format.
Write a number to a device at an I2C address using a specified number format.
```sig
pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
```
### ~hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
### ~
## Parameters
* ``address``: the 7-bit I2C address to which to send ``value``
* ``value``: the number to send to ``address``
* ``format``: the number format for ``value``. Formats include
**Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
**Int8BE**, **UInt8BE**, **Int16BE**, **UInt16BE**, and
**Int32BE**.
* **Int** stands for "integer", and **UInt** stands for "unsigned integer".
* **LE** stands for "little-endian" and **BE** stands for "big-endian".
* The number in each format name stands for the number of bits in the format.
* ``repeated`` repeated start, true - don't send stop at end
* **address**: the 7-bit I2C address of the device to send to send **value** to.
* **value**: the number to send to **address**.
* **format**: the [NumberFormat](/types/buffer/number-format) for **value**.
* **repeated**: if `true`, a [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure the number is written to the device with out an interruption. If set to `false` (the default), the data is written without setting a start condition more than once.
## Example
The following example sends the value `2055` to the 7-bit I2C
address `32` in big-endian 32-bit integer format.
Send the value `2055` to the 7-bit I2C address as a 32-bit number. The `32`, big-endian, and integer chosen for the format.
```blocks
pins.i2cWriteNumber(32, 2055, NumberFormat.Int32BE);
```
### ~hint
This function is not supported in the simulator.
### ~
## See also
[I2C](https://en.wikipedia.org/wiki/I%C2%B2C)
[What's I2C?](http://www.i2c-bus.org/), [number format](/types/buffer/number-format)

32
docs/reference/serial/read-buffer.md
View File

@ -1,19 +1,39 @@
# Serial Read Buffer
# read Buffer
Read the buffered serial data as a buffer.
Read available serial data into a buffer.
```sig
serial.readBuffer(64);
```
## Parameters
* **length**: the [number](/types/number) of characters of serial data to read.
## Returns
* a Buffer containing input from the serial port. The length of the buffer may be smaller than the requested length.
* a [buffer](/types/buffer) containing input from the serial port. The length of the buffer may be smaller than the requested length.
## Remarks
## ~hint
**Pause for more data**
If the desired number of characters are available, this will return a string with the expected size. Otherwise, the calling fiber sleeps until the desired number of characters have been read.
If the desired number of characters are available, **readBuffer** returns a buffer with the expected size. If not, the calling fiber (the part of your program calling the **readBuffer** function) sleeps until the desired number of characters are finally read into the buffer.
The need to pause for more data is set by the @boardname@ **[serial mode](https://lancaster-university.github.io/microbit-docs/ubit/serial/#serial-modes)**.
## ~
## Example
Read character data from the serial port one row at a time. Write the rows to an LED display connected to the I2C pins.
```blocks
let rowData: Buffer = null;
for (let i = 0; i < 24; i++) {
rowData = serial.readBuffer(80);
pins.i2cWriteBuffer(65, rowData, false);
}
```
## See Also
[micro:bit DAL documentation](https://lancaster-university.github.io/microbit-docs/ubit/serial/#managedstring-read-int-size-microbitserialmode-mode)
[write buffer](/reference/serial/write-buffer)

20
docs/reference/serial/write-buffer.md
View File

@ -1,4 +1,4 @@
# Serial Write Buffer
# write Buffer
Write a buffer to the [serial](/device/serial) port.
@ -6,6 +6,22 @@ Write a buffer to the [serial](/device/serial) port.
serial.writeBuffer(pins.createBuffer(0));
```
You place your data characters into an existing buffer. All of the data, the length of the buffer, is written to the serial port.
## Parameters
* `buffer` is the buffer to write to the serial port
* **buffer**: a [buffer](/types/buffer) to write to the serial port.
## Example
Read some characters of data from a device connected to the I2C pins. Write the data to the serial port.
```blocks
pins.i2cWriteNumber(132, NumberFormat.UInt8LE, 0);
let i2cBuffer = pins.i2cReadBuffer(132, 16, false);
serial.writeBuffer(i2cBuffer);
```
## See also
[read buffer](/reference/serial/read-buffer)

4
docs/types/buffer/number-format.md
View File

@ -65,8 +65,8 @@ The formats for numbers stored on the @boardname@ are:
* `UInt16LE`: two bytes, unsigned, little endian
* `Int16BE`: two bytes, signed, big endian
* `UInt16BE`: two bytes, unsigned, big endian
* `Int32LE`: four bytes, unsigned, little endian
* `Int32BE`: four bytes, unsigned, big endian
* `Int32LE`: four bytes, signed, little endian
* `Int32BE`: four bytes, signed, big endian
## See also

2
docs/types/buffer/using-buffers.md
View File

@ -19,7 +19,7 @@ function getTimeData() {
}
```
The command to read the time uses just one number so we use **i2cWriteNumber** to send this command. The time data that the RTC gives us comes back as a buffer from **i2cReadBuffer**.
The command to read the time uses just one number so we use [i2cWriteNumber](/reference/pins/i2c-write-number) to send this command. The time data that the RTC gives us comes back as a buffer from [i2cReadBuffer](/reference/pins/i2c-read-buffer).
## Reading from a buffer