Serial Port to Webhook Forwarder

A Python application that listens to a serial port and forwards each line to a webhook endpoint. Designed to run as a systemd service on Ubuntu 24.04.

Features

• Reads data from serial port line by line
• Posts each line to a configurable webhook endpoint
• Automatic retry logic for both serial connection and webhook posting
• Runs as a systemd service with automatic restart
• Comprehensive logging to systemd journal
• Configurable via JSON configuration file or command-line arguments

Requirements

• Python 3.12
• Ubuntu 24.04 (or other systemd-based Linux)
• Serial port device (e.g., /dev/ttyUSB0)

Installation

1. Install Python dependencies

sudo apt update
sudo apt install python3 python3-pip python3-venv

2. Create application directory

sudo mkdir -p /opt/serial-webhook
sudo mkdir -p /etc/serial-webhook

3. Copy files

# Copy the Python script
sudo cp serial_webhook.py /opt/serial-webhook/
sudo chmod +x /opt/serial-webhook/serial_webhook.py

# Copy and configure the config file
sudo cp config.json.example /etc/serial-webhook/config.json
sudo nano /etc/serial-webhook/config.json  # Edit with your settings

4. Install Python dependencies

sudo pip3 install --break-system-packages pyserial requests
# Or create a virtual environment (recommended):
# cd /opt/serial-webhook
# python3 -m venv venv
# source venv/bin/activate
# pip install -r requirements.txt
# Then update ExecStart in the service file to use the venv python

5. Configure the service

Edit /etc/serial-webhook/config.json with your settings:

{
  "serial_port": "/dev/ttyUSB0",
  "webhook_url": "https://your-domain.com/webhook",
  "baudrate": 9600,
  "retry_attempts": 3,
  "retry_delay": 5
}

6. Install systemd service

# Copy service file
sudo cp serial-webhook.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable serial-webhook.service

# Start the service
sudo systemctl start serial-webhook.service

Configuration

Configuration File Options

• serial_port: Serial port device path (e.g., /dev/ttyUSB0, /dev/ttyACM0)
• webhook_url: HTTP(S) endpoint to POST data to
• baudrate: Serial port baud rate (default: 9600)
• retry_attempts: Number of retry attempts for failed operations (default: 3)
• retry_delay: Delay in seconds between retry attempts (default: 5)

Webhook Payload Format

The application sends POST requests with JSON payload:

{
  "data": "the line read from serial port",
  "timestamp": 1234567890.123,
  "source": "/dev/ttyUSB0"
}

Usage

Check service status

sudo systemctl status serial-webhook.service

View logs

# View recent logs
sudo journalctl -u serial-webhook.service -n 50

# Follow logs in real-time
sudo journalctl -u serial-webhook.service -f

# View logs since today
sudo journalctl -u serial-webhook.service --since today

Stop the service

sudo systemctl stop serial-webhook.service

Restart the service

sudo systemctl restart serial-webhook.service

Disable service from starting on boot

sudo systemctl disable serial-webhook.service

Troubleshooting

Permission denied on serial port

Add the user to the dialout group:

sudo usermod -a -G dialout root

Or check the serial port permissions:

ls -l /dev/ttyUSB0
sudo chmod 666 /dev/ttyUSB0

Finding your serial port

List available serial ports:

ls -l /dev/tty*
# or
dmesg | grep tty

Testing serial port manually

# Install screen
sudo apt install screen

# Connect to serial port
screen /dev/ttyUSB0 9600

Manual testing

Run the script manually for testing:

cd /opt/serial-webhook
python3 serial_webhook.py --serial-port /dev/ttyUSB0 --webhook-url https://your-domain.com/webhook --debug

Common Serial Port Devices

• USB-to-Serial adapters: /dev/ttyUSB0, /dev/ttyUSB1, etc.
• Arduino and similar: /dev/ttyACM0, /dev/ttyACM1, etc.
• Raspberry Pi GPIO serial: /dev/ttyAMA0 or /dev/serial0

Security Notes

• The service runs as root by default to ensure serial port access
• Consider creating a dedicated user with appropriate permissions for production use
• Use HTTPS for webhook URLs to encrypt data in transit
• The systemd service includes security hardening options