Skip to content

Commit 8eb31a1

Browse files
author
Brendan Whitfield
committed
added troubleshooting page
1 parent 55286b0 commit 8eb31a1

6 files changed

Lines changed: 143 additions & 57 deletions

File tree

‎docs/Async Connections.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,19 @@ connection.stop()
3939

4040
---
4141

42-
## start()
42+
### start()
4343

4444
Starts the update loop.
4545

4646
---
4747

48-
## stop()
48+
### stop()
4949

5050
Stops the update loop.
5151

5252
---
5353

54-
## paused()
54+
### paused()
5555

5656
A helper function for use in a Context Manager (a `with` statement) to temporarily stop the update loop. This makes it easy to protect your `watch()` and `unwatch()` calls. If the update loop was running at the time of being paused, it will be restarted upon exitting the context block. For instance:
5757

@@ -75,23 +75,23 @@ if was_running:
7575

7676
---
7777

78-
## watch(command, callback=None, force=False)
78+
### watch(command, callback=None, force=False)
7979

8080
*Note: The async loop must be stopped or paused before this function can be called*
8181

8282
Subscribes a command to be continuously updated. After calling `watch()`, the `query()` function will return the latest `Response` from that command. An optional callback can also be set, and will be fired upon receipt of new values. Multiple callbacks for the same command are welcome. An optional `force` parameter will force an unsupported command to be sent.
8383

8484
---
8585

86-
## unwatch(command, callback=None)
86+
### unwatch(command, callback=None)
8787

8888
*Note: The async loop must be stopped or paused before this function can be called*
8989

9090
Unsubscribes a command from being updated. If no callback is specified, all callbacks for that command are dropped. If a callback is given, only that callback is unsubscribed (all others remain live).
9191

9292
---
9393

94-
## unwatch_all()
94+
### unwatch_all()
9595

9696
*Note: The async loop must be stopped or paused before this function can be called*
9797

‎docs/Command Table Methods.md‎

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

‎docs/Command Tables.md‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11

2-
Python-OBD has built in tables for the most common commands. They can be looked up by name, or by mode/PID (for a full list, see [Command Tables](https://github.com/brendanwhitfield/python-OBD/wiki/Command-Tables)).
2+
# Lookup
3+
4+
Python-OBD has built in tables for the most common commands. They can be looked up by name, or by mode & PID.
35

46
```python
57
import obd
@@ -15,7 +17,45 @@ c = obd.commands['RPM']
1517
c = obd.commands[1][12] # mode 1, PID 12 (RPM)
1618
```
1719

18-
<br>
20+
The `commands` table also has a few helper methods for determining if a particular name or PID is present.
21+
22+
---
23+
24+
### has_command(command)
25+
26+
Checks the internal command tables for the existance of the given `OBDCommand` object. Commands are compared by mode and PID value.
27+
28+
```python
29+
import obd
30+
obd.commands.has_command(obd.commands.RPM) # True
31+
```
32+
33+
---
34+
35+
### has_name(name)
36+
37+
Checks the internal command tables for a command with the given name. This is also the function of the `in` operator.
38+
39+
```python
40+
import obd
41+
42+
obd.commands.has_name('RPM') # True
43+
44+
# OR
45+
46+
'RPM' in obd.commands # True
47+
```
48+
49+
---
50+
51+
### has_pid(mode, pid)
52+
53+
Checks the internal command tables for a command with the given mode and PID.
54+
55+
```python
56+
import obd
57+
obd.commands.has_pid(1, 12) # True
58+
```
1959

2060
---
2161

‎docs/OBD Connections.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
12
After installing the library, simply `import obd`, and create a new OBD connection object. By default, python-OBD will scan for Bluetooth and USB serial ports (in that order), and will pick the first connection it finds. The port can also be specified manually by passing a connection string to the OBD constructor. You can also use the scanSerial helper retrieve a list of connected ports.
23

34
```python
@@ -20,11 +21,11 @@ connection = obd.OBD(ports[0]) # connect to the first port in the list
2021

2122
---
2223

23-
## query(command, force=False)
24+
### query(command, force=False)
2425

2526
Sends an `OBDCommand` to the car, and returns a `OBDResponse` object. This function will block until a response is recieved 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.
2627

27-
*For non-blocking querying, see [Async Querying](https://github.com/brendanwhitfield/python-OBD/wiki/Async-Querying)*
28+
*For non-blocking querying, see [Async Querying](Async Connections.md)*
2829

2930
```python
3031
import obd
@@ -35,31 +36,31 @@ r = connection.query(obd.commands.RPM) # returns the response from the car
3536

3637
---
3738

38-
## is_connected()
39+
### is_connected()
3940

4041
Returns a boolean for whether a connection was established.
4142

4243
---
4344

44-
## get_port_name()
45+
### get_port_name()
4546

4647
Returns the string name for the currently connected port (`"/dev/ttyUSB0"`). If no connection was made, this function returns `"Not connected to any port"`.
4748

4849
---
4950

50-
## supports(command)
51+
### supports(command)
5152

5253
Returns a boolean for whether a command is supported by both the car and python-OBD
5354

5455
---
5556

56-
## close()
57+
### close()
5758

5859
Closes the connection.
5960

6061
---
6162

62-
## supported_commands
63+
### supported_commands
6364

6465
Property containing a list of commands that are supported by the car.
6566

‎docs/Troubleshooting.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
2+
# Debug Output
3+
4+
If python-OBD is not working properly, the first thing you should do is enable debug output. The following line enables console printing:
5+
6+
```python
7+
obd.debug.console = True
8+
```
9+
10+
Here are some common logs from python-OBD, and their meanings:
11+
12+
<br>
13+
14+
### Successful Connection
15+
16+
```none
17+
[obd] ========================== python-OBD (v0.4.0) ==========================
18+
[obd] Explicit port defined
19+
[obd] Opening serial port '/dev/pts/2'
20+
[obd] Serial port successfully opened on /dev/pts/2
21+
[obd] write: 'ATZ\r\n'
22+
[obd] wait: 1 seconds
23+
[obd] read: 'ATZ\rELM327 v2.1\r'
24+
[obd] write: 'ATE0\r\n'
25+
[obd] read: 'ATE0\rOK\r'
26+
[obd] write: 'ATH1\r\n'
27+
[obd] read: 'OK\r'
28+
[obd] write: 'ATL0\r\n'
29+
[obd] read: 'OK\r'
30+
[obd] write: 'ATSPA8\r\n'
31+
[obd] read: 'OK\r'
32+
[obd] write: '0100\r\n'
33+
[obd] read: '7E8 06 41 00 FF FF FF FF FC\r'
34+
[obd] write: 'ATDPN\r\n'
35+
[obd] read: 'A8\r'
36+
[obd] Connection successful
37+
[obd] querying for supported PIDs (commands)...
38+
[obd] Sending command: 0100: Supported PIDs [01-20]
39+
[obd] write: '0100\r\n'
40+
[obd] read: '7E8 06 41 00 FF FF FF FF FC\r'
41+
[obd] Sending command: 0120: Supported PIDs [21-40]
42+
[obd] write: '0120\r\n'
43+
[obd] read: '7E8 06 41 20 FF FF FF FF FC\r'
44+
[obd] Sending command: 0140: Supported PIDs [41-60]
45+
[obd] write: '0140\r\n'
46+
[obd] read: '7E8 06 41 40 FF FF FF FE FB\r'
47+
[obd] finished querying with 93 commands supported
48+
[obd] =========================================================================
49+
```
50+
51+
<br>
52+
53+
### Non-responsive ELM
54+
55+
```
56+
[obd] ========================== python-OBD (v0.4.0) ==========================
57+
[obd] Explicit port defined
58+
[obd] Opening serial port '/dev/pts/2'
59+
[obd] Serial port successfully opened on /dev/pts/2
60+
[obd] write: 'ATZ\r\n'
61+
[obd] wait: 1 seconds
62+
[obd] __read() found nothing
63+
[obd] __read() found nothing
64+
[obd] __read() never recieved prompt character
65+
[obd] read: ''
66+
[obd] write: 'ATE0\r\n'
67+
[obd] __read() found nothing
68+
[obd] __read() found nothing
69+
[obd] __read() never recieved prompt character
70+
[obd] read: ''
71+
[obd] Connection Error:
72+
[obd] ATE0 did not return 'OK'
73+
[obd] Failed to connect
74+
[obd] =========================================================================
75+
```
76+
77+
This is likely a problem with the serial connection between the OBD-II adapter and your computer. Make sure that:
78+
79+
- bluetooth devices have been paired properly
80+
- you are connecting to the right port in `/dev` (or that there is any port at all)
81+
- you have the correct permissions to write to the port
82+
83+
---
84+
85+
<br>

‎mkdocs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ pages:
55
- Home: 'index.md'
66
- OBD Connections: 'OBD Connections.md'
77
- Commands: 'OBD Commands.md'
8-
- Custom Commands: 'Custom Commands.md'
98
- Command Tables: 'Command Tables.md'
10-
- Command Table Methods: 'Command Table Methods.md'
9+
- Custom Commands: 'Custom Commands.md'
1110
- Responses: 'OBD Responses.md'
1211
- Async Connections: 'Async Connections.md'
1312
- Debug: 'Debug.md'
13+
- Troubleshooting: 'Troubleshooting.md'
1414

1515
theme: readthedocs

0 commit comments

Comments
 (0)