Skip to content

Commit a8f33a7

Browse files
jhhocsjhhocs
authored
Added infrastructure docs (#3)
* Added infrastructure docs * Fixed notes
1 parent 0edcab7 commit a8f33a7

12 files changed

+10404
-0
lines changed

‎package-lock.json

Lines changed: 9483 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎public/digi-xbee-rr-802-15-4-rf-module-datasheet.pdf

1.22 MB
Binary file not shown.

‎src/content/docs/gcs/Infrastructure/XBee Serial Library/api.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: XBee Serial API
3+
description: API for XBee serial library
4+
---
5+
API for the XBee serial library
6+
## Constructor
7+
8+
9+
> ```py
10+
> __init__(port=None, baudrate=115200, status=False, logger=None)
11+
>```
12+
13+
Configure the serial port
14+
15+
:::note[Note]
16+
Serial ports are not opened on object creation.
17+
:::
18+
19+
<br>
20+
21+
| <!-- --> | <!-- --> |
22+
| - | - |
23+
| **Parameters** | <ul><li>**port** (`str` or `None`) - Port of serial device.</li><li>**baudrate** (`int`) - Baudrate of serial device.</li><li>**status** (`bool`) - Automatically receive status packets after a transmission.</li><li>**logger** (`Logger`) - Logger object from Logger.Logger used to record data such as sent and received data.</li></ul> |
24+
25+
<br>
26+
27+
See [Serial Port][serial_port] for details on finding the correct serial port name.
28+
29+
*baudrate* should be the same for both device (XBee RF module) and serial port. XBees will be configured to 115200 by default.
30+
31+
See [Frame Details][transmit_status] for details regarding the XBee status packet (Frame type `0x89`).
32+
33+
A `Logger` instance will be created if it is not provided. You should only create your own instance of `Logger` if you want to log data that is not already logged by the XBee library.
34+
35+
**Example:**
36+
37+
```py
38+
from Communication.XBee.XBee import XBee
39+
40+
PORT = "/dev/cu.usbserial-D30DWZKT"
41+
BAUD_RATE = 115200
42+
xbee = XBee(PORT, BAUD_RATE) # status and logger will be set to False and None respectively
43+
```
44+
45+
## Methods
46+
47+
> ```py
48+
> open()
49+
>```
50+
Open a connection over the serial port. This method does not return anything if a port is successfully opened.
51+
52+
<br>
53+
54+
| <!-- --> | <!-- --> |
55+
| - | - |
56+
| **Returns** | `True` if success, `False` if failure (There is already an open port) |
57+
| **Raises:** | `SerialException` if there is an error opening the serial port. |
58+
59+
<br>
60+
61+
A `SerialException` typically occurs if:
62+
* The XBee module is not plugged in
63+
* The port/device name is incorrect
64+
* The port is in use (e.g. There is another program accessing the same port )
65+
66+
> ```py
67+
> close()
68+
> ```
69+
70+
Close a connection over the serial port.
71+
72+
<br>
73+
74+
| <!-- --> | <!-- --> |
75+
| - | - |
76+
| **Returns** | `True` if success, `False` if failure. |
77+
| **Return type** | `bool` |
78+
79+
<br>
80+
81+
> ```py
82+
> transmit_data(data, address="0000000000000000")
83+
> ```
84+
85+
Send data to another XBee module(s)
86+
87+
<br>
88+
89+
| <!-- --> | <!-- --> |
90+
| - | - |
91+
| **Parameters** | <ul><li>**data** (`str`) - String data to transmit.</li><li>**address** (`str`) - Address of destination XBee module. `"0000000000000000"` if no value is provided.</li></ul> |
92+
| **Returns** | Status of transmit request. See [0x89 Tx (Transmit) Status][transmit_status] for more details. |
93+
| **Return type** | `x89` or `None` |
94+
| **Raises** | `SerialException` if serial port is not open |
95+
96+
*data* can be at most 100 bytes (100 characters)
97+
98+
*address* can be set to `000000000000FFFF` in order to broadcast a message
99+
100+
0x89: (frame_type, frame_id, status)
101+
102+
Returns `None` if no status frame is received
103+
104+
<br>
105+
106+
> ```py
107+
> retrieve_data()
108+
> ```
109+
110+
111+
Check for incomming data
112+
113+
<br>
114+
115+
| <!-- --> | <!-- --> |
116+
| - | - |
117+
| **Returns** | `str` if there is incomming data. `None` otherwise.
118+
| **Return type** | `0x81` or `None`
119+
<!-- | **Raises** | `SerialException` if serial port is not open | -->
120+
121+
0x81: (frame_type, source_address, rssi, options, data)
122+
123+
<br>
124+
125+
:::note[Note]
126+
The below methods are used by GCS for testing.
127+
:::
128+
129+
130+
131+
> ```py
132+
> request_at_command_data(self, id)
133+
> ```
134+
135+
Request and retrieve configuration detail of XBee device.
136+
137+
| <!-- --> | <!-- --> |
138+
| - | - |
139+
| **Parameters** | **id** (`str`) - Identifier of AT command |
140+
| **Returns** | AT command response. See [0x88 AT Command Response][at_command_response] for more details. |
141+
| **Return type** | `0x88`|
142+
| **Raises** | `SerialException` if serial port is not open |
143+
144+
145+
<!-- Links -->
146+
[serial_port]: ./serial_port.md
147+
[frame_details]: ./frame_details.md
148+
[transmit_status]: ./frame_details.md#xbee-transmit-statusapi-mode---frame-type-89
149+
[at_command_response]: ./frame_details.md#0x88---at-command-response
150+
151+
> ```py
152+
> read_config(self, filename)
153+
> ```
154+
155+
:::caution[Caution]
156+
This method will be completely rewritten.
157+
:::
158+
159+
This method reads a config file and executes AT commands to retrieve configuration data of an XBee module. All returned data is written to a log file.
160+
161+
| <!-- --> | <!-- --> |
162+
| - | - |
163+
| **Parameters** | **filename** (`str`) - Filename of AT Commands to execute.
164+
| **Raises** | `SerialException` if serial port is not open |
165+
<!-- | **Returns** | AT command response. See [0x88 AT Command Response][at_command_response] for more details. |
166+
| **Return type** | `0x88`| -->

‎src/content/docs/gcs/Infrastructure/XBee Serial Library/examples.md

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
title: XBee Serial API Usage Guide
3+
description: Examples of how to use the xbee serial library
4+
---
5+
This guide provides examples of how to use the XBee API for **GCS and vehicle communication**.
6+
7+
## Table of Contents
8+
- [1️⃣ Initializing the XBee Connection](#1️⃣-initializing-the-xbee-connection)
9+
- [2️⃣ Closing the XBee Connection](#2️⃣-closing-the-xbee-connection)
10+
- [3️⃣ Sending Data to a Specified XBee Address](#3️⃣-sending-data-to-a-specified-xbee-address)
11+
- [4️⃣ Receiving Data from Another XBee](#4️⃣-receiving-data-from-another-xbee)
12+
13+
---
14+
## **1️⃣ Initializing the XBee Connection**
15+
This example shows how to **open an XBee connection** before sending or receiving data.
16+
17+
### **Methods Used:**
18+
- `XBee.__init__(port, baudrate, status, logger)`
19+
- `XBee.open()`
20+
21+
### **Parameters:**
22+
| Parameter | Type | Description |
23+
|-----------|------|-------------|
24+
| `port` | `str` | Serial port name (e.g., `/dev/cu.usbserial-D30DWZKY`) |
25+
| `baudrate` | `int` | XBee baud rate (default: `115200`) |
26+
| `status` | `bool` | Enable automatic status reception (default: `False`) |
27+
| `logger` | `Logger` | Logger instance for debugging |
28+
29+
### **Returns:**
30+
- `True` if the connection opens successfully.
31+
- `False` if it fails.
32+
33+
:::note[Note]
34+
`Logger` is not required. It is used for **testing and debugging** in GCS but can be omitted (logger=None).
35+
:::
36+
37+
### **Example:**
38+
```python
39+
from Communication.XBee import XBee
40+
from Logger.Logger import Logger
41+
42+
# Configuration
43+
PORT = "/dev/cu.usbserial-D30DWZKY"
44+
BAUD_RATE = 115200
45+
LOGGER = Logger()
46+
47+
# Initialize XBee
48+
xbee = XBee(port=PORT, baudrate=BAUD_RATE, logger=LOGGER)
49+
50+
# Open XBee connection
51+
if xbee.open():
52+
print("[INFO] XBee connection opened successfully.")
53+
else:
54+
print("[ERROR] Failed to open XBee connection.")
55+
```
56+
[🔼 Back to Table of Contents](#table-of-contents)
57+
58+
59+
<br>
60+
61+
## **2️⃣ Closing the XBee Connection**
62+
This example demonstrates how to **properly close the XBee serial connection** when it is no longer needed.
63+
64+
### **Methods Used:**
65+
- XBee.close()
66+
67+
### **Returns:**
68+
- `True` if the serial port is successfully closed.
69+
- `False` if the port is already closed or an error occurs.
70+
71+
:::note[Note]
72+
It is good practice to **always close the XBee connection** when it is no longer in use to free up system resources.
73+
:::
74+
### **Example:**
75+
```python
76+
from Communication.XBee import XBee
77+
78+
# Configuration
79+
PORT = "/dev/cu.usbserial-D30DWZKY"
80+
BAUD_RATE = 115200
81+
82+
# Initialize XBee without Logger
83+
xbee = XBee(port=PORT, baudrate=BAUD_RATE, logger=None)
84+
85+
# Open the XBee connection
86+
if xbee.open():
87+
print("[INFO] XBee connection opened successfully.")
88+
89+
# Perform communication tasks here...
90+
91+
# Close the connection
92+
if xbee.close():
93+
print("[INFO] XBee connection closed successfully.")
94+
else:
95+
print("[WARNING] XBee was already closed.")
96+
else:
97+
print("[ERROR] Failed to open XBee connection.")
98+
```
99+
[🔼 Back to Table of Contents](#table-of-contents)
100+
101+
102+
<br>
103+
104+
## **3️⃣ Sending Data to a Specified XBee Address**
105+
This example demonstrates how to **send data from GCS to a vehicle (or any XBee module)** using the `transmit_data()` method.
106+
107+
### **Methods Used:**
108+
- `XBee.transmit_data(data, address, retrieveStatus)`
109+
110+
### **Parameters:**
111+
| Parameter | Type | Description |
112+
|-----------|------|-------------|
113+
| `data` | `str` | The message or command to be sent. |
114+
| `address` | `str` | The 64-bit address of the destination XBee module. Use `"0000000000000000"` for **broadcast**. |
115+
| `retrieveStatus` | `bool` | If `True`, retrieves a transmit status response. |
116+
117+
### **Returns:**
118+
- `True` if the transmission is **successful**.
119+
- `False` if the **serial port is closed** or an error occurs.
120+
121+
:::note[Note]
122+
This method **does not confirm** whether the message was delivered successfully to the target. You should check the **Transmit Status Frame (`0x89`)** to confirm delivery. This method is still work-in-progress. Once the functionality of receiving a **Transmit Status Frame (`0x89`)** is implemented, a new example will be added.
123+
:::
124+
125+
### **Example:**
126+
```python
127+
from Communication.XBee import XBee
128+
129+
# Configuration
130+
PORT = "/dev/cu.usbserial-D30DWZKY"
131+
BAUD_RATE = 115200
132+
DEST_ADDRESS = "0013A20040B5XXXX" # Replace with actual 64-bit address
133+
134+
# Initialize XBee without Logger
135+
xbee = XBee(port=PORT, baudrate=BAUD_RATE, logger=None)
136+
137+
# Open XBee connection
138+
if xbee.open():
139+
print("[INFO] XBee connection opened successfully.")
140+
141+
# Message to send
142+
message = "Hello Vehicle, this is GCS!"
143+
144+
# Send data to the specified XBee address
145+
if xbee.transmit_data(data=message, address=DEST_ADDRESS, retrieveStatus=False):
146+
print(f"[INFO] Data sent to {DEST_ADDRESS} successfully.")
147+
else:
148+
print(f"[ERROR] Failed to send data to {DEST_ADDRESS}.")
149+
150+
# Close XBee connection after sending data
151+
xbee.close()
152+
else:
153+
print("[ERROR] Failed to open XBee connection.")
154+
```
155+
[🔼 Back to Table of Contents](#table-of-contents)
156+
157+
<br>
158+
159+
## **4️⃣ Receiving Data from Another XBee**
160+
This example demonstrates how to **retrieve incoming data packets** from a vehicle using `retrieve_data()`.
161+
162+
### **Methods Used:**
163+
- `XBee.retrieve_data()`
164+
165+
### **Returns:**
166+
- A decoded message if data is received successfully.
167+
- `None` if no data is available.
168+
169+
:::note[Note]
170+
Ensure that the XBee connection is **open** before attempting to retrieve data.
171+
:::
172+
173+
### **Example:**
174+
```python
175+
from Communication.XBee import XBee
176+
177+
# Configuration
178+
PORT = "/dev/cu.usbserial-D30DWZKY"
179+
BAUD_RATE = 115200
180+
181+
# Initialize and open XBee connection
182+
xbee = XBee(port=PORT, baudrate=BAUD_RATE)
183+
184+
if xbee.open():
185+
print("[INFO] XBee connection opened. Listening for incoming data...")
186+
187+
while True:
188+
try:
189+
received_data = xbee.retrieve_data()
190+
191+
if received_data:
192+
print(f"[INFO] Received Data: {received_data}")
193+
except KeyboardInterrupt:
194+
print("\n[INFO] Stopping data reception.")
195+
break
196+
else:
197+
print("[ERROR] Failed to open XBee connection.")
198+
```
199+
200+
[🔼 Back to Table of Contents](#table-of-contents)
201+
202+
203+

‎src/content/docs/gcs/Infrastructure/XBee Serial Library/files/digi-xbee-rr-802-15-4-rf-module-datasheet.pdf

1.22 MB
Binary file not shown.

0 commit comments

Comments
 (0)