Skip to content

Commit 266eb29

Browse files
author
Brendan Whitfield
committed
Merge branch 'devel'
2 parents dcc99ec + b4fcfaa commit 266eb29

40 files changed

Lines changed: 2707 additions & 1136 deletions

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,12 @@ import obd
2020

2121
connection = obd.OBD() # auto-connects to USB or RF port
2222

23-
cmd = obd.commands.RPM # select an OBD command (sensor)
23+
cmd = obd.commands.SPEED # select an OBD command (sensor)
2424

2525
response = connection.query(cmd) # send the command, and parse the response
2626

27-
print(response.value)
28-
print(response.unit)
27+
print(response.value) # returns unit-bearing values thanks to Pint
28+
print(response.value.to("mph")) # user-friendly unit conversions
2929
```
3030

3131
Documentation

‎docs/Command Lookup.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
`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.
2+
3+
```python
4+
import obd
5+
6+
c = obd.commands.RPM
7+
8+
# OR
9+
10+
c = obd.commands['RPM']
11+
12+
# OR
13+
14+
c = obd.commands[1][12] # mode 1, PID 12 (RPM)
15+
```
16+
17+
The `commands` table also has a few helper methods for determining if a particular name or PID is present.
18+
19+
---
20+
21+
### has_command(command)
22+
23+
Checks the internal command tables for the existance of the given `OBDCommand` object. Commands are compared by mode and PID value.
24+
25+
```python
26+
import obd
27+
obd.commands.has_command(obd.commands.RPM) # True
28+
```
29+
30+
---
31+
32+
### has_name(name)
33+
34+
Checks the internal command tables for a command with the given name. This is also the function of the `in` operator.
35+
36+
```python
37+
import obd
38+
39+
obd.commands.has_name('RPM') # True
40+
41+
# OR
42+
43+
'RPM' in obd.commands # True
44+
```
45+
46+
---
47+
48+
### has_pid(mode, pid)
49+
50+
Checks the internal command tables for a command with the given mode and PID.
51+
52+
```python
53+
import obd
54+
obd.commands.has_pid(1, 12) # True
55+
```
56+
57+
---
58+
59+
<br>

‎docs/Command Tables.md‎

Lines changed: 263 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/Commands.md‎

Lines changed: 0 additions & 233 deletions
This file was deleted.

‎docs/Connections.md‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,21 @@ connection = obd.OBD("/dev/ttyUSB0") # create connection with USB 0
1212

1313
# OR
1414

15-
ports = obd.scan_serial() # return list of valid USB or RF ports
15+
ports = obd.scan_serial() # return list of valid USB or RF ports
1616
print ports # ['/dev/ttyUSB0', '/dev/ttyUSB1']
1717
connection = obd.OBD(ports[0]) # connect to the first port in the list
1818
```
1919

2020

2121
<br>
2222

23-
### OBD(portstr=None, baudrate=38400, protocol=None, fast=True):
23+
### OBD(portstr=None, baudrate=None, protocol=None, fast=True):
2424

2525
`portstr`: The UNIX device file or Windows COM Port for your adapter. The default value (`None`) will auto select a port.
2626

27-
`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
27+
`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.
2828

29-
`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.
29+
`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.
3030

3131
`fast`: Allows commands to be optimized before being sent to the car. Python-OBD currently makes two such optimizations:
3232

@@ -41,7 +41,7 @@ Disabling fast mode will guarantee that python-OBD outputs the unaltered command
4141

4242
### query(command, force=False)
4343

44-
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.
44+
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.
4545

4646
*For non-blocking querying, see [Async Querying](Async Connections.md)*
4747

@@ -87,13 +87,7 @@ connection.status() == OBDStatus.CAR_CONNECTED
8787

8888
### port_name()
8989

90-
Returns the string name for the currently connected port (`"/dev/ttyUSB0"`). If no connection was made, this function returns `"Not connected to any port"`.
91-
92-
---
93-
94-
### get_port_name()
95-
96-
**Deprecated:** use `port_name()` instead
90+
Returns the string name for the currently connected port (`"/dev/ttyUSB0"`). If no connection was made, this function returns an empty string.
9791

9892
---
9993

@@ -148,8 +142,17 @@ Closes the connection.
148142

149143
### supported_commands
150144

151-
Property containing a list of commands that are supported by the car.
145+
Property containing a `set` of commands that are supported by the car.
146+
147+
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).
152148

149+
```python
150+
import obd
151+
connection = obd.OBD()
152+
153+
# manually mark the given command as supported
154+
connection.supported_commands.add(<OBDCommand>)
155+
```
153156
---
154157

155158
<br>

0 commit comments

Comments
 (0)