botibot.py 1.0.1

A python package for Project Botibot

botibot.py

A python package for Project Botibot - A collection of reusable, class-based utility modules for common Raspberry Pi microcontroller projects. These modules provide easy-to-use interfaces for controlling servos, OLED displays, relays, and web servers.

📦 Modules Overview

1. ServoController (modules/servo/)

• Purpose: Control servo motors with PWM signals
• Features:
  • Precise angle control (0-180°)
  • Sweep operations
  • Context manager support
  • Multiple positioning methods

2. OLEDDisplay (modules/oled/)

• Purpose: Control SSD1306-based I2C OLED displays
• Features:
  • Text and graphics rendering
  • Multi-line text support
  • Scrolling and blinking effects
  • Progress bars and status displays

3. RelayController (modules/relay/)

• Purpose: Control relay modules for switching circuits
• Features:
  • Single and multiple relay control
  • Timed operations
  • Pattern sequences (wave, blink)
  • Background timer support

4. FlaskServer (modules/webserver/)

• Purpose: Create configurable web interfaces and APIs
• Features:
  • Beautiful responsive web dashboard
  • RESTful API endpoints
  • Real-time data sharing
  • Custom route support

🛠 Installation

Option 1: Install from PyPI (Recommended)

# Install the package
pip install botibot.py

# Or install with all optional dependencies
pip install botibot.py[full]

Option 2: Install from Source

1. Clone the repository

   git clone https://github.com/deJames-13/botibot.py.git
   cd botibot
   

2. Install in development mode

   pip install -e .
   
   # Or with development dependencies
   pip install -e .[dev]
   

Option 3: Build and Install Local Package

# Build the package
python -m build

# Install the built package
pip install dist/*.whl

Hardware Setup

3. Enable I2C and SPI (if needed)

   sudo raspi-config
   # Navigate to Interfacing Options > I2C > Enable
   # Navigate to Interfacing Options > SPI > Enable
   

4. Test installation

   # Test CLI commands
   botibot-demo --help
   botibot-servo --help
   botibot-oled --help
   

🚀 Quick Start

Basic Usage Examples

Servo Control

from modules import ServoController

# Basic servo control
with ServoController(pin=11) as servo:
    servo.move_to_position(0, delay=1)    # 0 degrees
    servo.move_to_position(90, delay=1)   # 90 degrees
    servo.move_to_position(180, delay=1)  # 180 degrees
    servo.center()                        # Back to center

OLED Display

from modules import OLEDDisplay

# Create display and show text
oled = OLEDDisplay(width=128, height=64)
oled.write_text("Hello, Pi!", 0, 0)

# Multi-line display
lines = ["Line 1", "Line 2", "Line 3"]
oled.write_multiline(lines, 0, 0, line_height=12)

# Graphics
oled.draw_rectangle(10, 10, 50, 30)
oled.draw_circle(100, 25, 15)
oled.show()

Relay Control

from modules import RelayController

# Basic relay control
with RelayController(pin=17) as relay:
    relay.turn_on()
    time.sleep(2)
    relay.turn_off()
    
    # Pulse operation
    relay.pulse(duration=3.0)
    
    # Blinking
    relay.blink(on_time=0.5, off_time=0.5, cycles=5)

Web Server

from modules import FlaskServer

# Create web server
server = FlaskServer(name="My Pi Server", port=5000)

# Add data
server.set_data("temperature", 25.6)
server.set_data("status", "online")

# Add custom route
@server.add_route('/api/custom')
def custom_api():
    return {"message": "Hello from custom API!"}

# Start server
server.run()  # Visit http://localhost:5000

Complete Integration Example

from modules import ServoController, OLEDDisplay, RelayController, FlaskServer
import time
import threading

# Initialize components
servo = ServoController(pin=11)
oled = OLEDDisplay()
relay = RelayController(pin=17)
server = FlaskServer(name="Pi Lab Controller")

# Add web API routes
@server.add_route('/api/servo/<int:angle>', methods=['POST'])
def control_servo(angle):
    servo.set_angle(angle)
    return {"success": True, "angle": angle}

@server.add_route('/api/relay/<action>', methods=['POST'])
def control_relay(action):
    if action == 'on':
        relay.turn_on()
    elif action == 'off':
        relay.turn_off()
    return {"success": True, "action": action}

# Start web server in background
server.run(threaded=True)

# Update display with status
while True:
    oled.clear(show=False)
    oled.write_text("Pi Controller", 0, 0, show=False)
    oled.write_text(f"Time: {time.strftime('%H:%M:%S')}", 0, 20, show=True)
    time.sleep(1)

🎯 Running the Complete Demo

Run the comprehensive demo that showcases all modules:

python tests/demo_all_modules.py

This demo will:

• Initialize all hardware components
• Start a web server with control interface
• Run demonstration sequences
• Provide real-time status updates
• Enable remote control via web browser

Web Interface URLs:

• Dashboard: http://your-pi-ip:5000
• Control Panel: http://your-pi-ip:5000/control
• API Status: http://your-pi-ip:5000/api/status

🖥️ Command Line Interface

The package includes CLI tools for quick hardware testing:

Main Demo Command

# Run complete hardware demo
botibot-demo

# Run quick demo
botibot-demo --quick

Individual Component Commands

Servo Control:

# Set servo to specific angle
botibot-servo --pin 11 --angle 90

# Perform sweep operation
botibot-servo --pin 11 --sweep

# Center servo
botibot-servo --pin 11 --center

OLED Display:

# Display text
botibot-oled --text "Hello Raspberry Pi!"

# Clear display
botibot-oled --clear

# Run OLED demo
botibot-oled --demo

Relay Control:

# Turn relay on
botibot-relay --pin 17 --on

# Turn relay off
botibot-relay --pin 17 --off

# Toggle relay
botibot-relay --pin 17 --toggle

# Pulse relay for 3 seconds
botibot-relay --pin 17 --pulse 3.0

Web Server:

# Start web server
botibot-server --port 5000 --host 0.0.0.0

# Start with debug mode
botibot-server --port 8080 --debug

🔧 Hardware Connections

Servo Motor

• Signal Pin: GPIO 11 (Physical pin 23)
• Power: 5V (Physical pin 2)
• Ground: GND (Physical pin 6)

OLED Display (I2C)

• VCC: 3.3V (Physical pin 1)
• GND: GND (Physical pin 9)
• SDA: GPIO 2 (Physical pin 3)
• SCL: GPIO 3 (Physical pin 5)

Relay Module

• Signal Pin: GPIO 17 (Physical pin 11)
• VCC: 5V (Physical pin 4)
• GND: GND (Physical pin 14)

📚 API Reference

ServoController

• __init__(pin, pin_mode=GPIO.BOARD, frequency=50)
• set_angle(angle) - Set servo to specific angle (0-180°)
• move_to_position(angle, delay=0.5) - Move with delay
• sweep(start_angle=0, end_angle=180, step=10, delay=0.1, cycles=1)
• center(delay=0.5) - Move to 90° position
• cleanup() - Clean up resources

OLEDDisplay

• __init__(width=128, height=64, i2c_address=0x3C)
• write_text(text, x=0, y=0, font=None, fill=255, show=True)
• write_multiline(lines, x=0, y=0, line_height=10, ...)
• draw_rectangle(x, y, width, height, outline=255, fill=None)
• draw_circle(x, y, radius, outline=255, fill=None)
• scroll_text(text, y=0, delay=0.1, cycles=1)
• progress_bar(progress, x=0, y=30, width=100, height=10)

RelayController

• __init__(pin, pin_mode=GPIO.BCM, active_low=True)
• turn_on() - Turn relay ON
• turn_off() - Turn relay OFF
• toggle() - Toggle relay state
• pulse(duration=1.0) - Turn ON for duration then OFF
• blink(on_time=0.5, off_time=0.5, cycles=5)
• timed_on(duration, callback=None) - Non-blocking timed operation

FlaskServer

• __init__(name="RaspberryPi Server", host="0.0.0.0", port=5000)
• set_data(key, value) - Set shared data
• get_data(key, default=None) - Get shared data
• add_route(rule, methods=['GET']) - Add custom route decorator
• run(threaded=False) - Start server

🔍 Troubleshooting

Common Issues

1. Permission Errors

   sudo usermod -a -G gpio,i2c,spi $USER
   # Then log out and back in
   

2. I2C Not Working

   sudo raspi-config  # Enable I2C
   sudo i2cdetect -y 1  # Check for devices
   

3. GPIO Already in Use

   import RPi.GPIO as GPIO
   GPIO.cleanup()  # Clean up before running
   

4. Web Server Port in Use

   sudo lsof -i :5000  # Check what's using port 5000
   # Or use a different port in FlaskServer(port=8080)
   

📝 Examples Directory

Check the tests/ directory for demo and test files:

• demo_all_modules.py - Comprehensive demo showcasing all modules
• test_basic.py - Basic import and functionality tests

🤝 Contributing

1. Fork the repository at https://github.com/deJames-13/botibot.py
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Author: deJames-13
Email: [e-mail]
GitHub: https://github.com/deJames-13/botibot.py

🆘 Support

If you encounter issues:

1. Check the troubleshooting section
2. Verify hardware connections
3. Check the tests directory for reference implementations
4. Ensure all dependencies are installed
5. Open an issue at https://github.com/deJames-13/botibot.py/issues

---

Happy coding with your Raspberry Pi! 🍓

botibot.py - A python package for Project Botibot by deJames-13