rubberotter 1.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,215 @@
1
+ Metadata-Version: 2.4
2
+ Name: rubberotter
3
+ Version: 1.4.0
4
+ Summary: Comprehensive Python SDK, CLI, and Web App to discover, control, and manage Rubber Otter ATmega32U4 microcontrollers over USB CDC Serial and Bluetooth LE (BLE).
5
+ Author-email: AtaCanYmc <atacanymc@gmail.com>
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/AtaCanYmc/RubberOtter
8
+ Project-URL: Documentation, https://github.com/AtaCanYmc/RubberOtter#readme
9
+ Keywords: rubberotter,arduino,atmega32u4,hid,keyboard,mouse,ble,hm10,promicro,leonardo
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: System :: Hardware :: Hardware Drivers
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ Requires-Dist: pyserial>=3.5
21
+ Requires-Dist: bleak>=0.20.0
22
+ Requires-Dist: flask>=3.0.0
23
+
24
+ [← Back to Root Repository](../README.md)
25
+
26
+ # Rubber Otter Python SDK and CLI
27
+
28
+ Python client library, command-line interface, Model Context Protocol (MCP) server, and OtterDeck local web controller for the Rubber Otter USB HID ecosystem.
29
+
30
+ ## Table of Contents
31
+
32
+ - [Overview](#overview)
33
+ - [Installation](#installation)
34
+ - [Quick Start](#quick-start)
35
+ - [Model Context Protocol (MCP) Server](#model-context-protocol-mcp-server)
36
+ - [AI Agent Tool Registry](#ai-agent-tool-registry)
37
+ - [Python SDK Reference](#python-sdk-reference)
38
+ - [CLI Command Reference](#cli-command-reference)
39
+ - [OtterDeck Web Dashboard](#otterdeck-web-dashboard)
40
+ - [Testing](#testing)
41
+ - [Türkçe Özet](#türkçe-özet)
42
+
43
+ ## Overview
44
+
45
+ `rubberotter` communicates with Rubber Otter microcontrollers across two primary transport mechanisms:
46
+ 1. **Bluetooth Low Energy (BLE)**: Connects to HM-10 or ESP32 peripherals using Bleak. Auto-discovers devices by advertising name and GATT service UUID `0xFFE0`.
47
+ 2. **USB CDC Serial**: Connects directly to MCU serial endpoints using PySerial.
48
+
49
+ The library encapsulates packet framing, sequence counting, checksum generation, and ACK validation.
50
+
51
+ ## Installation
52
+
53
+ Install directly in editable development mode:
54
+
55
+ ```bash
56
+ cd python
57
+ pip install -e .
58
+ ```
59
+
60
+ Or install dependencies from `requirements.txt`:
61
+
62
+ ```bash
63
+ pip install -r requirements.txt
64
+ ```
65
+
66
+ ### Runtime Requirements
67
+ - Python 3.10 or higher.
68
+ - `bleak >= 0.20.0`
69
+ - `pyserial >= 3.5`
70
+ - `flask >= 3.0.0`
71
+
72
+ ## Quick Start
73
+
74
+ ```bash
75
+ # Scan for nearby BLE devices and USB ports
76
+ rubberotter scan
77
+
78
+ # Type text via USB HID
79
+ rubberotter type "Hello from Rubber Otter\n"
80
+
81
+ # Trigger a 150ms vibration pulse
82
+ rubberotter vibrate 150
83
+
84
+ # Toggle background mouse jiggler
85
+ rubberotter jiggler toggle
86
+ ```
87
+
88
+ ## Model Context Protocol (MCP) Server
89
+
90
+ Rubber Otter implements a JSON-RPC 2.0 stdio Model Context Protocol (MCP) server for integration with AI assistants such as Claude Desktop, Cursor, and Antigravity.
91
+
92
+ ### Running the Server
93
+
94
+ ```bash
95
+ # Start the stdio MCP server
96
+ rubberotter mcp
97
+
98
+ # Inspect registered MCP tools
99
+ rubberotter mcp --list-tools
100
+
101
+ # Output Claude Desktop configuration snippet
102
+ rubberotter mcp --config-claude
103
+
104
+ # Output Cursor configuration snippet
105
+ rubberotter mcp --config-cursor
106
+ ```
107
+
108
+ ### Claude Desktop Integration
109
+
110
+ Add the following block to your `claude_desktop_config.json`:
111
+
112
+ ```json
113
+ {
114
+ "mcpServers": {
115
+ "rubberotter": {
116
+ "command": "rubberotter",
117
+ "args": ["mcp"]
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ ## AI Agent Tool Registry
124
+
125
+ Export tool schemas directly to OpenAI function calling format or Anthropic tool definitions:
126
+
127
+ ```python
128
+ from rubberotter.ai.tools import RubberOtterToolRegistry
129
+
130
+ registry = RubberOtterToolRegistry()
131
+
132
+ # Export schemas for OpenAI Function Calling
133
+ openai_tools = [tool.to_openai_tool() for tool in registry.list_tools()]
134
+
135
+ # Export schemas for Anthropic Claude Tools
136
+ claude_tools = [tool.to_anthropic_tool() for tool in registry.list_tools()]
137
+
138
+ # Execute tool programmatically
139
+ result = registry.execute("rubberotter_type", {"text": "make test\n", "auto_enter": True})
140
+ print(result)
141
+ ```
142
+
143
+ ## Python SDK Reference
144
+
145
+ ### Synchronous Client (`RubberOtter`)
146
+
147
+ ```python
148
+ from rubberotter import RubberOtter
149
+
150
+ # Auto-discovers BLE device or USB serial port
151
+ with RubberOtter() as otter:
152
+ otter.vibrate(150)
153
+ otter.type("git status\n")
154
+ otter.delay(100)
155
+ otter.mouse_click("left")
156
+ otter.jiggler_toggle()
157
+ otter.macro_save("m0", 'vibrate 100 && type "echo done\n"')
158
+ otter.macro_run("m0")
159
+ ```
160
+
161
+ ### Asynchronous Client (`AsyncRubberOtter`)
162
+
163
+ ```python
164
+ import asyncio
165
+ from rubberotter import AsyncRubberOtter
166
+
167
+ async def run():
168
+ async with AsyncRubberOtter(use_ble=True) as otter:
169
+ ack = await otter.type_async("Async execution\n")
170
+ print("ACK Response:", ack)
171
+ await otter.vibrate_async(200)
172
+
173
+ asyncio.run(run())
174
+ ```
175
+
176
+ ## CLI Command Reference
177
+
178
+ | Command | Arguments | Description |
179
+ | :--- | :--- | :--- |
180
+ | `rubberotter scan` | `[--json]` | Scans for USB serial ports and BLE peripherals. |
181
+ | `rubberotter type` | `"<text>"` | Sends keystroke injection payload. |
182
+ | `rubberotter send` | `"<command>"` | Sends a raw framed protocol command string. |
183
+ | `rubberotter vibrate` | `<ms>` | Triggers vibration motor for duration in milliseconds. |
184
+ | `rubberotter jiggler` | `on \| off \| toggle` | Controls background mouse jiggler mode. |
185
+ | `rubberotter macro` | `list \| run \| save` | Manages EEPROM non-volatile macro slots. |
186
+ | `rubberotter serve` | `[--web-port 8080]` | Launches local OtterDeck web control panel. |
187
+ | `rubberotter mcp` | `[--list-tools]` | Starts Model Context Protocol stdio server. |
188
+
189
+ ## OtterDeck Web Dashboard
190
+
191
+ The package embeds a lightweight Flask dashboard for controlling the device through a local web interface:
192
+
193
+ ```bash
194
+ rubberotter serve --web-port 8080
195
+ ```
196
+
197
+ Access the interface at `http://127.0.0.1:8080`.
198
+
199
+ ## Testing
200
+
201
+ Run the Python unit test suite:
202
+
203
+ ```bash
204
+ python3 -m unittest discover -s tests -p "test_*.py"
205
+ ```
206
+
207
+ ## Türkçe Özet
208
+
209
+ Rubber Otter Python paketi, ATmega32U4 tabanlı Rubber Otter donanımını Bluetooth LE (HM-10 / ESP32) ve USB Seri Port üzerinden yönetmek için tasarlanmış istemci kütüphanesi, terminal aracı ve Model Context Protocol (MCP) sunucusudur.
210
+
211
+ Temel Yetenekler:
212
+ 1. **Model Context Protocol (MCP)**: Claude Desktop, Cursor ve yapay zeka ajanlarının işletim sistemi üzerinde doğrudan fare/klavye komutları yürütmesini sağlar.
213
+ 2. **Yapay Zeka Araç Kaydı**: OpenAI ve Anthropic formatında otomatik araç şemaları üretir.
214
+ 3. **Senkron ve Asenkron API**: Python betikleri için `RubberOtter` ve `AsyncRubberOtter` istemcileri sunar.
215
+ 4. **OtterDeck Arayüzü**: Dahili Flask sunucusu ile web üzerinden anlık test ve yönetim imkanı verir.
@@ -0,0 +1,192 @@
1
+ [← Back to Root Repository](../README.md)
2
+
3
+ # Rubber Otter Python SDK and CLI
4
+
5
+ Python client library, command-line interface, Model Context Protocol (MCP) server, and OtterDeck local web controller for the Rubber Otter USB HID ecosystem.
6
+
7
+ ## Table of Contents
8
+
9
+ - [Overview](#overview)
10
+ - [Installation](#installation)
11
+ - [Quick Start](#quick-start)
12
+ - [Model Context Protocol (MCP) Server](#model-context-protocol-mcp-server)
13
+ - [AI Agent Tool Registry](#ai-agent-tool-registry)
14
+ - [Python SDK Reference](#python-sdk-reference)
15
+ - [CLI Command Reference](#cli-command-reference)
16
+ - [OtterDeck Web Dashboard](#otterdeck-web-dashboard)
17
+ - [Testing](#testing)
18
+ - [Türkçe Özet](#türkçe-özet)
19
+
20
+ ## Overview
21
+
22
+ `rubberotter` communicates with Rubber Otter microcontrollers across two primary transport mechanisms:
23
+ 1. **Bluetooth Low Energy (BLE)**: Connects to HM-10 or ESP32 peripherals using Bleak. Auto-discovers devices by advertising name and GATT service UUID `0xFFE0`.
24
+ 2. **USB CDC Serial**: Connects directly to MCU serial endpoints using PySerial.
25
+
26
+ The library encapsulates packet framing, sequence counting, checksum generation, and ACK validation.
27
+
28
+ ## Installation
29
+
30
+ Install directly in editable development mode:
31
+
32
+ ```bash
33
+ cd python
34
+ pip install -e .
35
+ ```
36
+
37
+ Or install dependencies from `requirements.txt`:
38
+
39
+ ```bash
40
+ pip install -r requirements.txt
41
+ ```
42
+
43
+ ### Runtime Requirements
44
+ - Python 3.10 or higher.
45
+ - `bleak >= 0.20.0`
46
+ - `pyserial >= 3.5`
47
+ - `flask >= 3.0.0`
48
+
49
+ ## Quick Start
50
+
51
+ ```bash
52
+ # Scan for nearby BLE devices and USB ports
53
+ rubberotter scan
54
+
55
+ # Type text via USB HID
56
+ rubberotter type "Hello from Rubber Otter\n"
57
+
58
+ # Trigger a 150ms vibration pulse
59
+ rubberotter vibrate 150
60
+
61
+ # Toggle background mouse jiggler
62
+ rubberotter jiggler toggle
63
+ ```
64
+
65
+ ## Model Context Protocol (MCP) Server
66
+
67
+ Rubber Otter implements a JSON-RPC 2.0 stdio Model Context Protocol (MCP) server for integration with AI assistants such as Claude Desktop, Cursor, and Antigravity.
68
+
69
+ ### Running the Server
70
+
71
+ ```bash
72
+ # Start the stdio MCP server
73
+ rubberotter mcp
74
+
75
+ # Inspect registered MCP tools
76
+ rubberotter mcp --list-tools
77
+
78
+ # Output Claude Desktop configuration snippet
79
+ rubberotter mcp --config-claude
80
+
81
+ # Output Cursor configuration snippet
82
+ rubberotter mcp --config-cursor
83
+ ```
84
+
85
+ ### Claude Desktop Integration
86
+
87
+ Add the following block to your `claude_desktop_config.json`:
88
+
89
+ ```json
90
+ {
91
+ "mcpServers": {
92
+ "rubberotter": {
93
+ "command": "rubberotter",
94
+ "args": ["mcp"]
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ ## AI Agent Tool Registry
101
+
102
+ Export tool schemas directly to OpenAI function calling format or Anthropic tool definitions:
103
+
104
+ ```python
105
+ from rubberotter.ai.tools import RubberOtterToolRegistry
106
+
107
+ registry = RubberOtterToolRegistry()
108
+
109
+ # Export schemas for OpenAI Function Calling
110
+ openai_tools = [tool.to_openai_tool() for tool in registry.list_tools()]
111
+
112
+ # Export schemas for Anthropic Claude Tools
113
+ claude_tools = [tool.to_anthropic_tool() for tool in registry.list_tools()]
114
+
115
+ # Execute tool programmatically
116
+ result = registry.execute("rubberotter_type", {"text": "make test\n", "auto_enter": True})
117
+ print(result)
118
+ ```
119
+
120
+ ## Python SDK Reference
121
+
122
+ ### Synchronous Client (`RubberOtter`)
123
+
124
+ ```python
125
+ from rubberotter import RubberOtter
126
+
127
+ # Auto-discovers BLE device or USB serial port
128
+ with RubberOtter() as otter:
129
+ otter.vibrate(150)
130
+ otter.type("git status\n")
131
+ otter.delay(100)
132
+ otter.mouse_click("left")
133
+ otter.jiggler_toggle()
134
+ otter.macro_save("m0", 'vibrate 100 && type "echo done\n"')
135
+ otter.macro_run("m0")
136
+ ```
137
+
138
+ ### Asynchronous Client (`AsyncRubberOtter`)
139
+
140
+ ```python
141
+ import asyncio
142
+ from rubberotter import AsyncRubberOtter
143
+
144
+ async def run():
145
+ async with AsyncRubberOtter(use_ble=True) as otter:
146
+ ack = await otter.type_async("Async execution\n")
147
+ print("ACK Response:", ack)
148
+ await otter.vibrate_async(200)
149
+
150
+ asyncio.run(run())
151
+ ```
152
+
153
+ ## CLI Command Reference
154
+
155
+ | Command | Arguments | Description |
156
+ | :--- | :--- | :--- |
157
+ | `rubberotter scan` | `[--json]` | Scans for USB serial ports and BLE peripherals. |
158
+ | `rubberotter type` | `"<text>"` | Sends keystroke injection payload. |
159
+ | `rubberotter send` | `"<command>"` | Sends a raw framed protocol command string. |
160
+ | `rubberotter vibrate` | `<ms>` | Triggers vibration motor for duration in milliseconds. |
161
+ | `rubberotter jiggler` | `on \| off \| toggle` | Controls background mouse jiggler mode. |
162
+ | `rubberotter macro` | `list \| run \| save` | Manages EEPROM non-volatile macro slots. |
163
+ | `rubberotter serve` | `[--web-port 8080]` | Launches local OtterDeck web control panel. |
164
+ | `rubberotter mcp` | `[--list-tools]` | Starts Model Context Protocol stdio server. |
165
+
166
+ ## OtterDeck Web Dashboard
167
+
168
+ The package embeds a lightweight Flask dashboard for controlling the device through a local web interface:
169
+
170
+ ```bash
171
+ rubberotter serve --web-port 8080
172
+ ```
173
+
174
+ Access the interface at `http://127.0.0.1:8080`.
175
+
176
+ ## Testing
177
+
178
+ Run the Python unit test suite:
179
+
180
+ ```bash
181
+ python3 -m unittest discover -s tests -p "test_*.py"
182
+ ```
183
+
184
+ ## Türkçe Özet
185
+
186
+ Rubber Otter Python paketi, ATmega32U4 tabanlı Rubber Otter donanımını Bluetooth LE (HM-10 / ESP32) ve USB Seri Port üzerinden yönetmek için tasarlanmış istemci kütüphanesi, terminal aracı ve Model Context Protocol (MCP) sunucusudur.
187
+
188
+ Temel Yetenekler:
189
+ 1. **Model Context Protocol (MCP)**: Claude Desktop, Cursor ve yapay zeka ajanlarının işletim sistemi üzerinde doğrudan fare/klavye komutları yürütmesini sağlar.
190
+ 2. **Yapay Zeka Araç Kaydı**: OpenAI ve Anthropic formatında otomatik araç şemaları üretir.
191
+ 3. **Senkron ve Asenkron API**: Python betikleri için `RubberOtter` ve `AsyncRubberOtter` istemcileri sunar.
192
+ 4. **OtterDeck Arayüzü**: Dahili Flask sunucusu ile web üzerinden anlık test ve yönetim imkanı verir.
@@ -0,0 +1,36 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "rubberotter"
7
+ version = "1.4.0"
8
+ requires-python = ">=3.10"
9
+ description = "Comprehensive Python SDK, CLI, and Web App to discover, control, and manage Rubber Otter ATmega32U4 microcontrollers over USB CDC Serial and Bluetooth LE (BLE)."
10
+ readme = "README.md"
11
+ authors = [{ name = "AtaCanYmc", email = "atacanymc@gmail.com" }]
12
+ license = { text = "Apache-2.0" }
13
+ keywords = ["rubberotter", "arduino", "atmega32u4", "hid", "keyboard", "mouse", "ble", "hm10", "promicro", "leonardo"]
14
+ classifiers = [
15
+ "Development Status :: 5 - Production/Stable",
16
+ "Intended Audience :: Developers",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.10",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Topic :: System :: Hardware :: Hardware Drivers",
23
+ ]
24
+ dependencies = [
25
+ "pyserial>=3.5",
26
+ "bleak>=0.20.0",
27
+ "flask>=3.0.0",
28
+ ]
29
+
30
+ [project.scripts]
31
+ rubberotter = "rubberotter.cli:main"
32
+ otter-cli = "rubberotter.cli:main"
33
+
34
+ [project.urls]
35
+ Homepage = "https://github.com/AtaCanYmc/RubberOtter"
36
+ Documentation = "https://github.com/AtaCanYmc/RubberOtter#readme"
@@ -0,0 +1,30 @@
1
+ """
2
+ Rubber Otter Python SDK Package
3
+ Comprehensive library for discovering, controlling, and managing Rubber Otter microcontrollers.
4
+ """
5
+
6
+ from .protocol import build_frame, parse_ack, ProtocolError, PayloadTooLargeError
7
+ from .scanner import scan_serial_ports, scan_ble_devices, scan_all
8
+ from .client import RubberOtter, AsyncRubberOtter, RubberOtterConnectionError
9
+ from .ai.tools import RubberOtterToolRegistry, ToolDefinition
10
+ from .mcp.server import RubberOtterMcpServer, run_stdio_server
11
+
12
+ __version__ = "1.4.0" # x-release-please-version
13
+ __author__ = "Rubber Otter Developer"
14
+
15
+ __all__ = [
16
+ "RubberOtter",
17
+ "AsyncRubberOtter",
18
+ "RubberOtterConnectionError",
19
+ "scan_serial_ports",
20
+ "scan_ble_devices",
21
+ "scan_all",
22
+ "build_frame",
23
+ "parse_ack",
24
+ "ProtocolError",
25
+ "PayloadTooLargeError",
26
+ "RubberOtterToolRegistry",
27
+ "ToolDefinition",
28
+ "RubberOtterMcpServer",
29
+ "run_stdio_server",
30
+ ]
@@ -0,0 +1,7 @@
1
+ """
2
+ Entry point for running rubberotter via python -m rubberotter
3
+ """
4
+ from rubberotter.cli import main
5
+
6
+ if __name__ == "__main__":
7
+ main()
@@ -0,0 +1,11 @@
1
+ """Rubber Otter AI Agent Tool Integrations & Exporters."""
2
+
3
+ from rubberotter.ai.tools import (
4
+ ToolDefinition,
5
+ RubberOtterToolRegistry,
6
+ )
7
+
8
+ __all__ = [
9
+ "ToolDefinition",
10
+ "RubberOtterToolRegistry",
11
+ ]