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

I2C ref doc 'repeated' description (#1589)

Browse Source 
* I2C ref doc 'repeated' description

* Note the non-endianness for one byte formats

* trigger rebuild
This commit is contained in:
Galen Nickel 2018-11-15 21:57:39 -08:00 committed by Peli de Halleux
parent ac9f9d1553
commit a6e4f63dea
5 changed files with 73 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -9,6 +9,7 @@ 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.
@ -19,7 +20,13 @@ This function needs real hardware to work with. It's not supported in the simula
* **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.
* **repeated**: if `true`, don't send a stop condition after the read. Otherwise, a stop condition is sent when `false` (the default).
### ~ hint
A [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure that when you want to read data miltiple times from the device at once, it can happen without interruption. A start conditon is sent (if **repeated** is `true`) each time a buffer is read without a matching stop condition. When the last buffer is read, the stop conditon can be sent by setting **repeated** to `false`. For single reads, don't use **repeated** or set it to `false`.
### ~
## Returns

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

@ -1,4 +1,4 @@
# I2C Read Number
# i2c Read Number
Read one number from an I2C address using a specified number format.
@ -7,6 +7,7 @@ pins.i2cReadNumber(0, NumberFormat.Int8LE, false);
```
### ~hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
@ -17,14 +18,21 @@ This function needs real hardware to work with. It's not supported in the simula
* **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.
* **repeated**: if `true`, don't send a stop condition after the read. Otherwise, a stop condition is sent when `false` (the default).
### ~ hint
A [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure that when you want to read multiple numbers from the device at one time, it can happen without interruption. A start conditon is sent (if **repeated** is `true`) each time a number is read without a matching stop condition. When the last number is read, the stop conditon can be sent by setting **repeated** to `false`. For single reads, don't use **repeated** or set it to `false`.
### ~
## Returns
* a number from the device with the [NumberFormat](/types/buffer/number-format) you asked for.
## Example
## Examples
### Read a big endian number from a device
The following example reads a number in big-endian, 16-bit, unsigned integer
format from the 7-bit I2C address `32`.
@ -32,9 +40,23 @@ 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);
let inValue = pins.i2cReadNumber(32, NumberFormat.UInt16BE, false);
```
### Repeated reads
Read three bytes from a device at address `33` at one time.
```blocks
let nums: number[] = []
nums[0] = pins.i2cReadNumber(33, NumberFormat.UInt8LE, true)
nums[1] = pins.i2cReadNumber(33, NumberFormat.UInt8LE, true)
nums[2] = pins.i2cReadNumber(33, NumberFormat.UInt8LE, false)
```
## See also
[i2c write number](/reference/pins/i2c-write-number)
[What's I2C?](http://www.i2c-bus.org/), [number format](/types/buffer/number-format)

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

@ -9,6 +9,7 @@ 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.
@ -19,7 +20,13 @@ This function needs real hardware to work with. It's not supported in the simula
* **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.
* **repeated**: if `true`, don't send a stop condition after the write. Otherwise, a stop condition is sent when `false` (the default).
### ~ hint
A [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure that when you want to write data miltiple times from the device at once, it can happen without interruption. A start conditon is sent (if **repeated** is `true`) each time a buffer is written without a matching stop condition. When the last buffer is written, the stop conditon can be sent by setting **repeated** to `false`. For single writes, don't use **repeated** or set it to `false`.
### ~
## Example

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

@ -7,6 +7,7 @@ pins.i2cWriteNumber(0, 0, NumberFormat.Int8LE, true);
```
### ~hint
**Simulator**
This function needs real hardware to work with. It's not supported in the simulator.
@ -18,9 +19,17 @@ This function needs real hardware to work with. It's not supported in the simula
* **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.
* **repeated**: if `true`, don't send a stop condition after the write. Otherwise, a stop condition is sent when `false` (the default).
## Example
### ~ hint
A [repeated start condition](http://www.i2c-bus.org/repeated-start-condition/) is set to help make sure that when you want to write multiple numbers from the device at one time, it can happen without interruption. A start conditon is sent (if **repeated** is `true`) each time a number is written without a matching stop condition. When the last number is written, the stop conditon can be sent by setting **repeated** to `false`. For single writes, don't use **repeated** or set it to `false`.
### ~
## Examples
### Write a big endian number to a device
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.
@ -28,6 +37,18 @@ Send the value `2055` to the 7-bit I2C address as a 32-bit number. The `32`, big
pins.i2cWriteNumber(32, 2055, NumberFormat.Int32BE, false);
```
### Reapeted writes
Send three byte values to a device at address `33`.
```blocks
pins.i2cWriteNumber(33, 19, NumberFormat.Int32BE, true);
pins.i2cWriteNumber(33, 61, NumberFormat.Int32BE, true);
pins.i2cWriteNumber(33, 87, NumberFormat.Int32BE, false);
```
## See also
[i2c read number](/reference/pins/i2c-read-number)
[What's I2C?](http://www.i2c-bus.org/), [number format](/types/buffer/number-format)

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

@ -68,6 +68,12 @@ The formats for numbers stored on the @boardname@ are:
* `Int32LE`: four bytes, signed, little endian
* `Int32BE`: four bytes, signed, big endian
#### ~ hint
The one byte formats really don't have endianness because there is no ordering needed for just one byte. They are given format types though so that they are consistant with the multi-byte formats. So, there is no difference between `Int8LE` and `Int8BE`, or `UInt8LE` and `UInt8BE`.
#### ~
## See also
[buffer](/types/buffer)
[buffer](/types/buffer)