# SerialLink
SerialLink is a Python library designed to simplify serial communication with microcontrollers. It enables efficient and seamless data exchange without blocking code execution. By using configurable start and end markers, SerialLink ensures reliable message framing, making it an ideal tool for developers working with embedded systems or serial communication.
### Notes: Need the [arduino](https://github.com/Michael-Jalloh/Arduino-SerialLink) companion library
Key Features:
- Non-blocking Reads: No need for methods like readUntil("\n") that can hinder code flow.
- Marker-Based Communication: Automatically detects the start and end of data packets, reducing parsing complexity.
- Ease of Use: Simplified API for quick integration into projects.
SerialLink is perfect for anyone needing robust, non-blocking serial communication for real-time applications.
## Installation
Installing SerialLink is straightforward. It’s available via `pip` for easy installation.
### Using `pip`
Run the following command in your terminal or command prompt:
``` bash
pip install seriallink
```
### Manual Installation
If you prefer to install manually:
1. Clone the repository:
``` bash
git clone https://github.com/your-username/seriallink.git
```
2. Navigate to the project directory:
``` bash
cd seriallink
```
3. Install the library using setup.py:
``` bash
python setup.py install
```
## Getting Started
Using SerialLink to communicate with a microcontroller is simple and intuitive. This quick guide will help you set up and send your first message.
Note: Needs the companion arduino library at [Arduino SerialLink]()
### Step 1: Import SerialLink
Begin by importing the library in your Python script:
``` python
from seriallink import SerialLink
```
### Step 2: Initialize the Serial Connection
Create a SerialLink object by specifying the port and baud rate:
``` python
serial = SerialLink("/dev/ttyUSB0", 115200)
```
``` python
serial = SerialLink("/dev/ttyUSB0")
```
the default buadrate is 115200 and the startMarker is `<` and the endMarker is `>`.
### Step 3: Send Data
Send a message to your microcontroller:
``` python
serial.send("on")
```
### Step 4: Read Data
Receive data from the microcontroller without blocking:
``` python
serial.poll()
if serial.new_data:
data = serial.get_data()
print(f"Received {data})
```
### Step 5: Close the Connection
Always close the connection when done:
``` python
serial.close()
```
### Get serial ports
``` python
from seriallink import get_ports
ports = get_ports("USB") # Gets ports with usb devices connected in a list
print(ports[0])
```
## API Reference
The SerialLink library provides a straightforward API for serial communication. Below is a detailed reference to its primary methods and attributes.
`SerialLink` Class
Initialization
```
SerialLink(port: str, baudrate: int = 115200, start_marker: str = "<", end_marker: str = ">")
```
### Parameters:
- port (str): The serial port (e.g., "COM3", "/dev/ttyUSB0").
- baudrate (int): Communication speed (default: 9600).
- start_marker (str): Character marking the start of a message (default: <).
- end_marker (str): Character marking the end of a message (default: >).
### Methods
1. send(data: str)
Sends a message through the serial port.
- Parameters:
- data (str): The string message to send.
- Example:
``` python
serial.send("on")
```
2. poll()
Polls the serial port buffer for new data and buffers the data to be read.
``` python
serial.poll()
```
3. get_data()
Get new data from the buffer
``` python
if serial.new_data:
data = serial.get_data()
print(data)
```
4. flush_port()
Read and clear all data from the serial port buffer
``` python
serial.flush_port()
```
5. close()
close the serial port
``` python
serial.close()
```
### Attributes
- port: The port used for communication.
- baudrate: The baud rate of the connection.
- start_marker: The character marking the start of a message.
- end_marker: The character marking the end of a message.
## Examples
1. Basic Communication
Send a message to a microcontroller and read its response:
``` python
from seriallink import SerialLink
# Initialize SerialLink
serial = SerialLink(port="/dev/ttyUSB0", baudrate=115200)
# Send a message
serial.send("Hello, Microcontroller!")
# Poll for a response
serial.poll()
if serial.new_data:
response = serial.get_data()
print(f"Received: {response}")
# Close the connection
serial.close()
```
2. Custom Start and End Markers
Use custom markers to frame messages:
``` python
from seriallink import SerialLink
# Initialize with custom markers
serial = SerialLink(port="/dev/ttyUSB0", baudrate=115200, start_marker="{", end_marker="}")
# Send a message
serial.send("temp")
# Poll for the response
serial.poll()
if serial.new_data:
data = serial.get_data()
print(f"Sensor Data: {data}")
# Close the connection
serial.close()
```
3. Continuous Reading
Read messages in a loop without blocking the main program:
``` python
from seriallink import SerialLink
import time
# Initialize SerialLink
serial = SerialLink(port="/dev/ttyUSB", baudrate=9600)
try:
while True:
# Check for incoming data
serial.poll()
if serial.new_data:
data = serial.get_data()
print(f"Received: {data}")
time.sleep(0.1) # Avoid tight looping
except KeyboardInterrupt:
print("Stopping communication.")
finally:
serial.close()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Michael-Jalloh/SerialLink",
"name": "SerialLink",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "seriallink, serial, link, communication, microcontroller",
"author": "Michael Jalloh",
"author_email": "michaeljalloh19@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d6/25/2f56cb3855a46abece8306db035c290b16078c9a7c0b3f56a1a2e71f3f87/seriallink-1.0.0.tar.gz",
"platform": "any",
"description": "# SerialLink\nSerialLink is a Python library designed to simplify serial communication with microcontrollers. It enables efficient and seamless data exchange without blocking code execution. By using configurable start and end markers, SerialLink ensures reliable message framing, making it an ideal tool for developers working with embedded systems or serial communication.\n\n### Notes: Need the [arduino](https://github.com/Michael-Jalloh/Arduino-SerialLink) companion library\n\nKey Features:\n\n- Non-blocking Reads: No need for methods like readUntil(\"\\n\") that can hinder code flow.\n- Marker-Based Communication: Automatically detects the start and end of data packets, reducing parsing complexity.\n- Ease of Use: Simplified API for quick integration into projects.\n\nSerialLink is perfect for anyone needing robust, non-blocking serial communication for real-time applications.\n\n## Installation\nInstalling SerialLink is straightforward. It\u2019s available via `pip` for easy installation.\n\n### Using `pip`\n\nRun the following command in your terminal or command prompt:\n\n``` bash\npip install seriallink\n```\n\n### Manual Installation\n\nIf you prefer to install manually:\n\n1. Clone the repository:\n``` bash\ngit clone https://github.com/your-username/seriallink.git\n```\n2. Navigate to the project directory:\n``` bash\ncd seriallink\n```\n3. Install the library using setup.py:\n``` bash\npython setup.py install\n```\n\n## Getting Started\n\nUsing SerialLink to communicate with a microcontroller is simple and intuitive. This quick guide will help you set up and send your first message. \n\nNote: Needs the companion arduino library at [Arduino SerialLink]()\n\n### Step 1: Import SerialLink\n\nBegin by importing the library in your Python script:\n``` python\nfrom seriallink import SerialLink\n```\n\n### Step 2: Initialize the Serial Connection\n\nCreate a SerialLink object by specifying the port and baud rate:\n``` python\nserial = SerialLink(\"/dev/ttyUSB0\", 115200)\n```\n``` python\nserial = SerialLink(\"/dev/ttyUSB0\")\n```\nthe default buadrate is 115200 and the startMarker is `<` and the endMarker is `>`.\n\n### Step 3: Send Data\n\nSend a message to your microcontroller:\n``` python\nserial.send(\"on\")\n```\n\n### Step 4: Read Data\n\nReceive data from the microcontroller without blocking:\n``` python\nserial.poll()\nif serial.new_data:\n data = serial.get_data()\n print(f\"Received {data})\n```\n\n### Step 5: Close the Connection\n\nAlways close the connection when done:\n``` python\nserial.close()\n```\n\n### Get serial ports\n``` python\nfrom seriallink import get_ports\n\nports = get_ports(\"USB\") # Gets ports with usb devices connected in a list\nprint(ports[0])\n```\n\n## API Reference\nThe SerialLink library provides a straightforward API for serial communication. Below is a detailed reference to its primary methods and attributes.\n\n`SerialLink` Class\n\nInitialization\n```\nSerialLink(port: str, baudrate: int = 115200, start_marker: str = \"<\", end_marker: str = \">\")\n```\n\n### Parameters:\n\n- port (str): The serial port (e.g., \"COM3\", \"/dev/ttyUSB0\").\n- baudrate (int): Communication speed (default: 9600).\n- start_marker (str): Character marking the start of a message (default: <).\n- end_marker (str): Character marking the end of a message (default: >).\n\n### Methods\n\n1. send(data: str)\n \n Sends a message through the serial port.\n \n - Parameters:\n - data (str): The string message to send.\n - Example:\n ``` python\n serial.send(\"on\")\n ```\n2. poll()\n\n Polls the serial port buffer for new data and buffers the data to be read.\n ``` python\n serial.poll()\n ```\n3. get_data()\n\n Get new data from the buffer\n ``` python\n if serial.new_data:\n data = serial.get_data()\n print(data)\n ```\n4. flush_port()\n\n Read and clear all data from the serial port buffer\n ``` python\n serial.flush_port()\n ```\n5. close()\n\n close the serial port\n ``` python\n serial.close()\n ```\n\n### Attributes\n\n- port: The port used for communication.\n- baudrate: The baud rate of the connection.\n- start_marker: The character marking the start of a message.\n- end_marker: The character marking the end of a message.\n\n## Examples\n1. Basic Communication\n\n Send a message to a microcontroller and read its response:\n\n ``` python\n from seriallink import SerialLink \n\n # Initialize SerialLink \n serial = SerialLink(port=\"/dev/ttyUSB0\", baudrate=115200) \n\n # Send a message \n serial.send(\"Hello, Microcontroller!\") \n\n # Poll for a response\n serial.poll()\n if serial.new_data:\n response = serial.get_data() \n print(f\"Received: {response}\") \n\n # Close the connection \n serial.close() \n ```\n\n2. Custom Start and End Markers\n\n Use custom markers to frame messages: \n ``` python\n from seriallink import SerialLink \n\n # Initialize with custom markers \n serial = SerialLink(port=\"/dev/ttyUSB0\", baudrate=115200, start_marker=\"{\", end_marker=\"}\") \n\n # Send a message \n serial.send(\"temp\") \n\n # Poll for the response \n serial.poll()\n if serial.new_data:\n data = serial.get_data() \n print(f\"Sensor Data: {data}\") \n\n # Close the connection \n serial.close() \n ```\n\n3. Continuous Reading\n\n Read messages in a loop without blocking the main program:\n ``` python\n from seriallink import SerialLink \n import time \n\n # Initialize SerialLink \n serial = SerialLink(port=\"/dev/ttyUSB\", baudrate=9600) \n\n try: \n while True: \n # Check for incoming data\n serial.poll() \n \n if serial.new_data:\n data = serial.get_data() \n print(f\"Received: {data}\") \n time.sleep(0.1) # Avoid tight looping \n except KeyboardInterrupt: \n print(\"Stopping communication.\") \n finally: \n serial.close() \n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SerialLink is a Python library designed to simplify serial communication with microcontrollers",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Michael-Jalloh/SerialLink",
"issues": "https://github.com/Michael-Jalloh/SerialLink/issues",
"source": "https://github.com/Michael-Jalloh/SerialLink"
},
"split_keywords": [
"seriallink",
" serial",
" link",
" communication",
" microcontroller"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e85ba4e4768ac416d5f9b8fa7d318cc48a383a260686941260bc86e4ddc9e639",
"md5": "38e501a7a3c956b6117823e9547b7965",
"sha256": "47abedbfd84962c3e7c79d31263608392951e5cae407b41cc8bf3cea011999e0"
},
"downloads": -1,
"filename": "SerialLink-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38e501a7a3c956b6117823e9547b7965",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 4930,
"upload_time": "2024-12-01T18:12:24",
"upload_time_iso_8601": "2024-12-01T18:12:24.902111Z",
"url": "https://files.pythonhosted.org/packages/e8/5b/a4e4768ac416d5f9b8fa7d318cc48a383a260686941260bc86e4ddc9e639/SerialLink-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6252f56cb3855a46abece8306db035c290b16078c9a7c0b3f56a1a2e71f3f87",
"md5": "40e03c8dc6d4dca0ea9f7e71f47fc436",
"sha256": "aa9fda8222bd7e069d3add362fb17f2c3991b8ce41bb477c39b95ceaf0132ca7"
},
"downloads": -1,
"filename": "seriallink-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "40e03c8dc6d4dca0ea9f7e71f47fc436",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5145,
"upload_time": "2024-12-01T18:12:29",
"upload_time_iso_8601": "2024-12-01T18:12:29.647448Z",
"url": "https://files.pythonhosted.org/packages/d6/25/2f56cb3855a46abece8306db035c290b16078c9a7c0b3f56a1a2e71f3f87/seriallink-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-01 18:12:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Michael-Jalloh",
"github_project": "SerialLink",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "seriallink"
}
JSON
