Merge branch 'devel'

README.md

@@ -20,12 +20,12 @@ import obd
 
 connection = obd.OBD() # auto-connects to USB or RF port
 
-cmd = obd.commands.RPM # select an OBD command (sensor)
+cmd = obd.commands.SPEED # select an OBD command (sensor)
 
 response = connection.query(cmd) # send the command, and parse the response
 
-print(response.value)
-print(response.unit)
+print(response.value) # returns unit-bearing values thanks to Pint
+print(response.value.to("mph")) # user-friendly unit conversions
 ```
 
 Documentation

docs/Command Lookup.md

@@ -0,0 +1,59 @@
+`OBDCommand`s are objects used to query information from the vehicle. They contain all of the information neccessary to perform the query, and decode the cars response. Python-OBD has [built in tables](Command Tables.md) for the most common commands. They can be looked up by name, or by mode & PID.
+
+```python
+import obd
+
+c = obd.commands.RPM
+
+# OR
+
+c = obd.commands['RPM']
+
+# OR
+
+c = obd.commands[1][12] # mode 1, PID 12 (RPM)
+```
+
+The `commands` table also has a few helper methods for determining if a particular name or PID is present.
+
+---
+
+### has_command(command)
+
+Checks the internal command tables for the existance of the given `OBDCommand` object. Commands are compared by mode and PID value.
+
+```python
+import obd
+obd.commands.has_command(obd.commands.RPM) # True
+```
+
+---
+
+### has_name(name)
+
+Checks the internal command tables for a command with the given name. This is also the function of the `in` operator.
+
+```python
+import obd
+
+obd.commands.has_name('RPM') # True
+
+# OR
+
+'RPM' in obd.commands # True
+```
+
+---
+
+### has_pid(mode, pid)
+
+Checks the internal command tables for a command with the given mode and PID.
+
+```python
+import obd
+obd.commands.has_pid(1, 12) # True
+```
+
+---
+
+<br>

docs/Connections.md

@@ -12,21 +12,21 @@ connection = obd.OBD("/dev/ttyUSB0") # create connection with USB 0
 
 # OR
 
-ports = obd.scan_serial()       # return list of valid USB or RF ports
+ports = obd.scan_serial()      # return list of valid USB or RF ports
 print ports                    # ['/dev/ttyUSB0', '/dev/ttyUSB1']
 connection = obd.OBD(ports[0]) # connect to the first port in the list
 ```
 
 
 <br>
 
-### OBD(portstr=None, baudrate=38400, protocol=None, fast=True):
+### OBD(portstr=None, baudrate=None, protocol=None, fast=True):
 
 `portstr`: The UNIX device file or Windows COM Port for your adapter. The default value (`None`) will auto select a port.
 
-`baudrate`: The baudrate at which to set the serial connection. This can vary from adapter to adapter. Typical values are: 9600, 38400, 19200, 57600, 115200
+`baudrate`: The baudrate at which to set the serial connection. This can vary from adapter to adapter. Typical values are: 9600, 38400, 19200, 57600, 115200. The default value (`None`) will auto select a baudrate.
 
-`protocol`: Forces python-OBD to use the given protocol when communicating with the adapter. See `protocol_id()` for possible values. The default value (`None`) will auto select a protocol.
+`protocol`: Forces python-OBD to use the given protocol when communicating with the adapter. See [protocol_id()](Connections.md/#protocol_id) for possible values. The default value (`None`) will auto select a protocol.
 
 `fast`: Allows commands to be optimized before being sent to the car. Python-OBD currently makes two such optimizations:
 
@@ -41,7 +41,7 @@ Disabling fast mode will guarantee that python-OBD outputs the unaltered command
 
 ### query(command, force=False)
 
-Sends an `OBDCommand` to the car, and returns a `OBDResponse` object. This function will block until a response is received from the car. This function will also check whether the given command is supported by your car. If a command is not marked as supported, it will not be sent to the car, and an empty `Response` will be returned. To force an unsupported command to be sent, there is an optional `force` parameter for your convenience.
+Sends an `OBDCommand` to the car, and returns an `OBDResponse` object. This function will block until a response is received from the car. This function will also check whether the given command is supported by your car. If a command is not marked as supported, it will not be sent, and an empty `OBDResponse` will be returned. To force an unsupported command to be sent, there is an optional `force` parameter for your convenience.
 
 *For non-blocking querying, see [Async Querying](Async Connections.md)*
 
@@ -87,13 +87,7 @@ connection.status() == OBDStatus.CAR_CONNECTED
 
 ### port_name()
 
-Returns the string name for the currently connected port (`"/dev/ttyUSB0"`). If no connection was made, this function returns `"Not connected to any port"`.
-
----
-
-### get_port_name()
-
-**Deprecated:** use `port_name()` instead
+Returns the string name for the currently connected port (`"/dev/ttyUSB0"`). If no connection was made, this function returns an empty string.
 
 ---
 
@@ -148,8 +142,17 @@ Closes the connection.
 
 ### supported_commands
 
-Property containing a list of commands that are supported by the car.
+Property containing a `set` of commands that are supported by the car.
+
+If you wish to manually mark a command as supported (prevents having to use `query(force=True)`), add the command to this set. This is not necessary when using python-OBD's builtin commands, but is useful if you create [custom commands](Custom Commands.md).
 
+```python
+import obd
+connection = obd.OBD()
+
+# manually mark the given command as supported
+connection.supported_commands.add(<OBDCommand>)
+```
 ---
 
 <br>