Browse Source

Minor syntax fixes for the 1-wire docs

Marcel Stör 8 years ago
parent
commit
e86347acf3
2 changed files with 50 additions and 48 deletions
  1. 49 47
      docs/en/modules/ow.md
  2. 1 1
      mkdocs.yml

+ 49 - 47
docs/en/modules/ow.md

@@ -1,9 +1,11 @@
-# onewire Module
+# 1-Wire Module
+
+This module provides functions to work with the [1-Wire](https://en.wikipedia.org/wiki/1-Wire) device communications bus system.
 
 ## ow.check_crc16()
-Compute the 1-Wire CRC16 and compare it against the received CRC.
+Computes the 1-Wire CRC16 and compare it against the received CRC.
 
-####Syntax
+#### Syntax
 `ow.check_crc16(buf, inverted_crc0, inverted_crc1[, crc])`
 
 #### Parameters
@@ -13,10 +15,10 @@ Compute the 1-Wire CRC16 and compare it against the received CRC.
   - `crc` CRC starting value (optional)
 
 #### Returns
-`bool` true, if the CRC matches; false for mismatch.
+true if the CRC matches, false otherwise
 
 ## ow.crc16()
-Compute a Dallas Semiconductor 16 bit CRC.  This is required to check the integrity of data received from many 1-Wire devices.  Note that the CRC computed here is **not** what you'll get from the 1-Wire network, for two reasons:
+Computes a Dallas Semiconductor 16 bit CRC.  This is required to check the integrity of data received from many 1-Wire devices.  Note that the CRC computed here is **not** what you'll get from the 1-Wire network, for two reasons:
 
 1. The CRC is transmitted bitwise inverted.
 2. Depending on the endian-ness of your processor, the binary representation of the two-byte return value may have a different byte order than the two bytes you get from 1-Wire.
@@ -25,98 +27,98 @@ Compute a Dallas Semiconductor 16 bit CRC.  This is required to check the integr
 `ow.crc16(buf[, crc])`
 
 #### Parameters
-  - `buf` string value, data to be calculated check sum in string.
-  - `crc` CRC starting value (optional)
+- `buf` string value, data to be calculated check sum in string
+- `crc` CRC starting value (optional)
 
 #### Returns
-`crc16` the CRC16, as defined by Dallas Semiconductor.
+the CRC16 as defined by Dallas Semiconductor
 
 ## ow.crc8()
-Compute a Dallas Semiconductor 8 bit CRC, these are used in the ROM and scratchpad registers.
+Computes a Dallas Semiconductor 8 bit CRC, these are used in the ROM and scratchpad registers.
 
 #### Syntax
 `ow.crc8(buf)`
 
 #### Parameters
-`buf` string value, data to be calculated check sum in string.
+`buf` string value, data to be calculated check sum in string
 
 #### Returns
-CRC result as byte.
+CRC result as byte
 
 ## ow.depower()
-Stop forcing power onto the bus. You only need to do this if you used the 'power' flag to `ow.write()` or used a `ow.write_bytes()` and aren't about to do another read or write.
+Stops forcing power onto the bus. You only need to do this if you used the 'power' flag to `ow.write()` or used a `ow.write_bytes()` and aren't about to do another read or write.
 
 #### Syntax
 `ow.depower(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
 `nil`
 
 ####See also
-  - [ow.write()](#owwrite)
-  - [ow.write_bytes()](#owwrite_bytes)
+- [ow.write()](#owwrite)
+- [ow.write_bytes()](#owwrite_bytes)
 
 ## ow.read()
-Read a byte.
+Reads a byte.
 
 ####Syntax
 `ow.read(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
-Byte read from slave device.
+byte read from slave device
 
 ## ow.read_bytes()
-Read multi bytes.
+Reads multi bytes.
 
 #### Syntax
 `ow.read_bytes(pin, size)`
 
 #### Parameters
-  - `pin` 1~12, IO index
-  - `size` number of bytes to be read from slave device
+- `pin` 1~12, I/O index
+- `size` number of bytes to be read from slave device
 
 #### Returns
 `string` bytes read from slave device
 
 ## ow.reset()
-Perform a 1-Wire reset cycle.
+Performs a 1-Wire reset cycle.
 
 #### Syntax
 `ow.reset(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
-  - `1` if a device responds with a presence pulse.
-  - `0` if there is no device or the bus is shorted or otherwise held low for more than 250 µS.
+- `1` if a device responds with a presence pulse
+- `0` if there is no device or the bus is shorted or otherwise held low for more than 250 µS
 
 ## ow.reset_search()
-Clear the search state so that it will start from the beginning again.
+Clears the search state so that it will start from the beginning again.
 
 #### Syntax
 `ow.reset_search(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
 `nil`
 
 ## ow.search()
-Look for the next device.
+Looks for the next device.
 
 #### Syntax
 `ow.search(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
 `rom_code` string with length of 8 upon success. It contains the rom code of slave device. Returns `nil` if search was unsuccessful.
@@ -125,14 +127,14 @@ Look for the next device.
 [ow.target_search()](#owtargetsearch)
 
 ## ow.select()
-Issue a 1-Wire rom select command. Make sure you do the `ow.reset(pin)` first.
+Issues a 1-Wire rom select command. Make sure you do the `ow.reset(pin)` first.
 
 #### Syntax
 `ow.select(pin, rom)`
 
 #### Parameters
-  - `pin` 1~12, IO index
-  - `rom` string value, len 8, rom code of the salve device
+- `pin` 1~12, I/O index
+- `rom` string value, len 8, rom code of the salve device
 
 #### Returns
 `nil`
@@ -195,38 +197,38 @@ end
 [ow.reset()](#owreset)
 
 ## ow.setup()
-Set a pin in onewire mode.
+Sets a pin in onewire mode.
 
 #### Syntax
 `ow.setup(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
 `nil`
 
 ## ow.skip()
-Issue a 1-Wire rom skip command, to address all on bus.
+Issues a 1-Wire rom skip command, to address all on bus.
 
 #### Syntax
 `ow.skip(pin)`
 
 #### Parameters
-`pin` 1~12, IO index
+`pin` 1~12, I/O index
 
 #### Returns
 `nil`
 
 ## ow.target_search()
-Set up the search to find the device type `family_code`. The search itself has to be initiated with a subsequent call to `ow.search()`.
+Sets up the search to find the device type `family_code`. The search itself has to be initiated with a subsequent call to `ow.search()`.
 
 #### Syntax
 `ow.target_search(pin, family_code)`
 
 #### Parameters
-  - `pin` 1~12, IO index
-  - `family_code` byte for family code
+- `pin` 1~12, I/O index
+- `family_code` byte for family code
 
 #### Returns
 `nil`
@@ -235,15 +237,15 @@ Set up the search to find the device type `family_code`. The search itself has t
 [ow.search()](#owsearch)
 
 ## ow.write()
-Write a byte. If `power` is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling `ow.depower()` or doing another read or write.
+Writes a byte. If `power` is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling `ow.depower()` or doing another read or write.
 
 #### Syntax
 `ow.write(pin, v, power)`
 
 #### Parameters
-  - `pin` 1~12, IO index
-  - `v` byte to be written to salve device 
-  - `power` 1 for wire being held high for parasitically powered devices
+- `pin` 1~12, I/O index
+- `v` byte to be written to salve device 
+- `power` 1 for wire being held high for parasitically powered devices
 
 #### Returns
 `nil`
@@ -252,15 +254,15 @@ Write a byte. If `power` is 1 then the wire is held high at the end for parasiti
 [ow.depower()](#owdepower)
 
 ## ow.write_bytes()
-Write multi bytes. If `power` is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling `ow.depower()` or doing another read or write.
+Writes multi bytes. If `power` is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling `ow.depower()` or doing another read or write.
 
 #### Syntax
 `ow.write_bytes(pin, buf, power)`
 
 #### Parameters
-  - `pin` 1~12, IO index
-  - `buf` string to be written to slave device
-  - `power` 1 for wire being held high for parasitically powered devices
+- `pin` 1~12, IO index
+- `buf` string to be written to slave device
+- `power` 1 for wire being held high for parasitically powered devices
 
 #### Returns
 `nil`

+ 1 - 1
mkdocs.yml

@@ -46,7 +46,7 @@ pages:
         - 'mqtt': 'en/modules/mqtt.md'
         - 'net': 'en/modules/net.md'
         - 'node': 'en/modules/node.md'
-        - 'ow': 'en/modules/ow.md'
+        - 'ow (1-Wire)': 'en/modules/ow.md'
         - 'pwm' : 'en/modules/pwm.md'
         - 'rtcmem': 'en/modules/rtcmem.md'
         - 'rtctime': 'en/modules/rtctime.md'