Add and update I2C topics (#602)

* Add and update I2C topics

* Throw in some edits for the serial buffer apis

* Add an example to serial read buffer

docs/reference/pins/i2c-read-buffer.md

@@ -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/)

docs/reference/pins/i2c-read-number.md

@@ -1,39 +1,40 @@
 # I2C Read Number
 
-Read one number from the specified 7-bit I2C address, in the specified
+Read one number from an I2C address using a specified number format.
-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.
+* **address**: the 7-bit I2C address of the device you want to read a number from.
-* ``format``: the number format. Formats include
+* **format**: the [NumberFormat](/types/buffer/number-format) of the number value to read.
-  **Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
+* **repeated**: repeated start, true - don't send stop at end.
-  **Int8BE**, **UInt8BE**, **Int16BE**, **UInt16BE**, and
+* **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.
-  **Int32BE**.
+
-  * **Int** stands for "integer", and **UInt** stands for "unsigned integer".
+## Returns
-  * **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.
+* a number from the device with the [NumberFormat](/types/buffer/number-format) you asked for.
-* ``repeated`` repeated start, true - don't send stop at end
 
 ## 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)

docs/reference/pins/i2c-write-buffer.md

@@ -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/)

docs/reference/pins/i2c-write-number.md

@@ -1,40 +1,33 @@
-# I2C Write Number
+# i2c Write Number
 
-Write the specified number to the specified 7-bit I2C address in the
+Write a number to a device at an I2C address using a specified number format.
-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``
+* **address**: the 7-bit I2C address of the device to send to send **value** to.
-* ``value``: the number to send to ``address``
+* **value**: the number to send to **address**.
-* ``format``: the number format for ``value``. Formats include
+* **format**: the [NumberFormat](/types/buffer/number-format) for **value**.
-  **Int8LE**, **UInt8LE**, **Int16LE**, **UInt16LE**, **Int32LE**,
+* **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.
-  **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
 
 ## Example
 
-The following example sends the value `2055` to the 7-bit I2C
+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.
-address `32` in big-endian 32-bit integer 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)

docs/reference/serial/read-buffer.md

@@ -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)

docs/reference/serial/write-buffer.md

@@ -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)

docs/types/buffer/number-format.md

@@ -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
+* `Int32LE`: four bytes, signed, little endian
-* `Int32BE`: four bytes, unsigned, big endian
+* `Int32BE`: four bytes, signed, big endian
 
 ## See also
 

docs/types/buffer/using-buffers.md

@@ -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