rubberorca 0.1.3__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,95 @@
1
+ Metadata-Version: 2.4
2
+ Name: rubberorca
3
+ Version: 0.1.3
4
+ Summary: Python SDK, CLI, and stdio MCP server for RubberOrca ESP32-S3 USB HID over BLE 5.0 GATT and USB CDC Serial.
5
+ Author-email: AtaCanYmc <atacanymc@gmail.com>
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/AtaCanYmc/RubberOrca
8
+ Project-URL: Repository, https://github.com/AtaCanYmc/RubberOrca
9
+ Project-URL: Issues, https://github.com/AtaCanYmc/RubberOrca/issues
10
+ Keywords: esp32-s3,usb-hid,ble,gatt,mcp,automation,rubberorca
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: System :: Hardware
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ Requires-Dist: bleak>=0.22
23
+ Requires-Dist: pyserial>=3.5
24
+
25
+ [Back to Root README](../README.md)
26
+
27
+ # RubberOrca Python SDK, CLI, and MCP Server
28
+
29
+ Unified Python package (`rubberorca`) providing a Python SDK, `rubberorca` CLI, and `rubberorca-mcp` stdio MCP server over BLE 5.0 GATT (`0xFFE0` / `0xFFE1`) and USB CDC Serial.
30
+
31
+ ## Installation
32
+
33
+ ```bash
34
+ pip install rubberorca
35
+ # Or editable from source:
36
+ pip install -e ./python
37
+ ```
38
+
39
+ ## Python SDK
40
+
41
+ ```python
42
+ from rubberorca import RubberOrca
43
+
44
+ orca = RubberOrca() # Auto-discovers BLE 0xFFE0 (or pass port="/dev/cu.usbmodem1101")
45
+ orca.type("hello from RubberOrca")
46
+ orca.key("enter")
47
+ orca.set_layout("tr_q")
48
+ orca.jiggler("toggle")
49
+ ```
50
+
51
+ ## Usage
52
+
53
+ ```bash
54
+ # Discover BLE 0xFFE0 devices and local serial ports
55
+ rubberorca scan
56
+
57
+ # Send commands over BLE (default)
58
+ rubberorca type "hello from RubberOrca"
59
+ rubberorca key enter
60
+ rubberorca media play_pause
61
+ rubberorca mouse move 40 -20
62
+ rubberorca jiggler toggle
63
+ rubberorca macro define m0 'type "git status" && enter'
64
+ rubberorca macro run m0
65
+ rubberorca ble-name "OrcaMini"
66
+ rubberorca raw-byte 0x32
67
+
68
+ # Send over USB CDC Serial instead of BLE
69
+ rubberorca --port /dev/cu.usbmodem1101 send 'type "ok" && enter'
70
+ ```
71
+
72
+ ## MCP Server
73
+
74
+ `rubberorca-mcp` exposes RubberOrca tools over stdio JSON-RPC 2.0 with zero extra dependencies (`scan_devices`, `type_text`, `press_key`, `media_control`, `mouse_action`, `jiggler`, `macro_define`, `macro_run`, `send_command`).
75
+
76
+ Example MCP client configuration (`mcp_config.json`):
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "rubberorca": {
82
+ "command": "rubberorca-mcp",
83
+ "args": []
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ Pass `--port /dev/cu.usbmodem1101` or `--address <BLE_ADDR>` in `args` (or set `RUBBERORCA_PORT` / `RUBBERORCA_ADDRESS`) to pin a specific device.
90
+
91
+ ## Testing
92
+
93
+ ```bash
94
+ python3 -m unittest discover -s python/tests -v
95
+ ```
@@ -0,0 +1,71 @@
1
+ [Back to Root README](../README.md)
2
+
3
+ # RubberOrca Python SDK, CLI, and MCP Server
4
+
5
+ Unified Python package (`rubberorca`) providing a Python SDK, `rubberorca` CLI, and `rubberorca-mcp` stdio MCP server over BLE 5.0 GATT (`0xFFE0` / `0xFFE1`) and USB CDC Serial.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ pip install rubberorca
11
+ # Or editable from source:
12
+ pip install -e ./python
13
+ ```
14
+
15
+ ## Python SDK
16
+
17
+ ```python
18
+ from rubberorca import RubberOrca
19
+
20
+ orca = RubberOrca() # Auto-discovers BLE 0xFFE0 (or pass port="/dev/cu.usbmodem1101")
21
+ orca.type("hello from RubberOrca")
22
+ orca.key("enter")
23
+ orca.set_layout("tr_q")
24
+ orca.jiggler("toggle")
25
+ ```
26
+
27
+ ## Usage
28
+
29
+ ```bash
30
+ # Discover BLE 0xFFE0 devices and local serial ports
31
+ rubberorca scan
32
+
33
+ # Send commands over BLE (default)
34
+ rubberorca type "hello from RubberOrca"
35
+ rubberorca key enter
36
+ rubberorca media play_pause
37
+ rubberorca mouse move 40 -20
38
+ rubberorca jiggler toggle
39
+ rubberorca macro define m0 'type "git status" && enter'
40
+ rubberorca macro run m0
41
+ rubberorca ble-name "OrcaMini"
42
+ rubberorca raw-byte 0x32
43
+
44
+ # Send over USB CDC Serial instead of BLE
45
+ rubberorca --port /dev/cu.usbmodem1101 send 'type "ok" && enter'
46
+ ```
47
+
48
+ ## MCP Server
49
+
50
+ `rubberorca-mcp` exposes RubberOrca tools over stdio JSON-RPC 2.0 with zero extra dependencies (`scan_devices`, `type_text`, `press_key`, `media_control`, `mouse_action`, `jiggler`, `macro_define`, `macro_run`, `send_command`).
51
+
52
+ Example MCP client configuration (`mcp_config.json`):
53
+
54
+ ```json
55
+ {
56
+ "mcpServers": {
57
+ "rubberorca": {
58
+ "command": "rubberorca-mcp",
59
+ "args": []
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Pass `--port /dev/cu.usbmodem1101` or `--address <BLE_ADDR>` in `args` (or set `RUBBERORCA_PORT` / `RUBBERORCA_ADDRESS`) to pin a specific device.
66
+
67
+ ## Testing
68
+
69
+ ```bash
70
+ python3 -m unittest discover -s python/tests -v
71
+ ```
@@ -0,0 +1,41 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "rubberorca"
7
+ version = "0.1.3"
8
+ description = "Python SDK, CLI, and stdio MCP server for RubberOrca ESP32-S3 USB HID over BLE 5.0 GATT and USB CDC Serial."
9
+ readme = "README.md"
10
+ license = { text = "Apache-2.0" }
11
+ requires-python = ">=3.9"
12
+ authors = [{ name = "AtaCanYmc", email = "atacanymc@gmail.com" }]
13
+ keywords = ["esp32-s3", "usb-hid", "ble", "gatt", "mcp", "automation", "rubberorca"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: Apache Software License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.9",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Topic :: System :: Hardware",
24
+ ]
25
+ dependencies = [
26
+ "bleak>=0.22",
27
+ "pyserial>=3.5",
28
+ ]
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/AtaCanYmc/RubberOrca"
32
+ Repository = "https://github.com/AtaCanYmc/RubberOrca"
33
+ Issues = "https://github.com/AtaCanYmc/RubberOrca/issues"
34
+
35
+ [project.scripts]
36
+ rubberorca = "rubberorca.cli:main"
37
+ rubberorca-mcp = "rubberorca.mcp_server:main"
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["."]
41
+ include = ["rubberorca*"]
@@ -0,0 +1,34 @@
1
+ from .protocol import (
2
+ ACK_LEN,
3
+ CHAR_UUID,
4
+ ETX,
5
+ PAYLOAD_MAX,
6
+ SERVICE_UUID,
7
+ STX,
8
+ VERSION,
9
+ Ack,
10
+ ProtocolError,
11
+ build_frame,
12
+ escape_text,
13
+ parse_ack,
14
+ )
15
+
16
+ from .sdk import RubberOrca
17
+
18
+ __version__ = "0.1.3" # x-release-please-version
19
+ __all__ = [
20
+ "ACK_LEN",
21
+ "Ack",
22
+ "CHAR_UUID",
23
+ "ETX",
24
+ "PAYLOAD_MAX",
25
+ "ProtocolError",
26
+ "RubberOrca",
27
+ "SERVICE_UUID",
28
+ "STX",
29
+ "VERSION",
30
+ "__version__",
31
+ "build_frame",
32
+ "escape_text",
33
+ "parse_ack",
34
+ ]
@@ -0,0 +1,172 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import asyncio
5
+ import sys
6
+ from typing import Optional
7
+
8
+ from .protocol import ProtocolError, escape_text
9
+ from .transport import list_serial_ports, scan_ble, send_command, send_raw_byte
10
+
11
+
12
+ def build_command_from_args(args: argparse.Namespace) -> str:
13
+ """Convert parsed CLI subcommand arguments into a RubberOrca wire command."""
14
+ cmd = args.command
15
+ if cmd == "send":
16
+ return args.payload
17
+ if cmd == "type":
18
+ return f'type "{escape_text(args.text)}"'
19
+ if cmd == "key":
20
+ return args.name
21
+ if cmd == "press":
22
+ if args.ms is not None:
23
+ return f"press {args.mod} {args.ms}"
24
+ return f"press {args.mod}"
25
+ if cmd == "media":
26
+ return f"media {args.action}"
27
+ if cmd == "mouse":
28
+ if args.mouse_cmd == "move":
29
+ return f"mouse move {args.dx} {args.dy}"
30
+ if args.mouse_cmd == "click":
31
+ return f"mouse click {args.button}"
32
+ if args.mouse_cmd == "scroll":
33
+ return f"mouse scroll {args.amount}"
34
+ if cmd == "jiggler":
35
+ return f"jiggler {args.state}"
36
+ if cmd == "macro":
37
+ if args.macro_cmd == "define":
38
+ return f"macro define {args.slot} {{ {args.body} }}"
39
+ if args.macro_cmd == "run":
40
+ return f"macro run {args.slot}"
41
+ if cmd == "ble-name":
42
+ return f'ble name "{args.name}"'
43
+ if cmd == "ble-passkey":
44
+ return f"ble passkey {args.passkey}"
45
+ if cmd == "layout":
46
+ return f"layout {args.name}"
47
+ raise ValueError(f"Unsupported command: {cmd}")
48
+
49
+
50
+ def build_parser() -> argparse.ArgumentParser:
51
+ parser = argparse.ArgumentParser(
52
+ prog="rubberorca",
53
+ description="Control RubberOrca ESP32-S3 USB HID over BLE 5.0 GATT or USB CDC Serial.",
54
+ )
55
+ parser.add_argument("--port", help="USB CDC serial port (uses BLE GATT when omitted)")
56
+ parser.add_argument("--address", help="Explicit BLE device address or UUID")
57
+ parser.add_argument("--baud", type=int, default=115200, help="Serial baud rate (default: 115200)")
58
+ parser.add_argument("--timeout", type=float, default=3.0, help="Transport timeout in seconds")
59
+ parser.add_argument("--seq", type=int, default=1, help="Packet sequence number (0-255)")
60
+
61
+ sub = parser.add_subparsers(dest="command", required=True)
62
+
63
+ sub.add_parser("scan", help="Scan for BLE 0xFFE0 devices and list serial ports")
64
+
65
+ p_send = sub.add_parser("send", help="Send a raw command or &&/; chain")
66
+ p_send.add_argument("payload", help="Raw command string")
67
+
68
+ p_type = sub.add_parser("type", help="Type text over USB HID keyboard")
69
+ p_type.add_argument("text", help="Text to type")
70
+
71
+ p_key = sub.add_parser("key", help="Send a single special key")
72
+ p_key.add_argument("name", choices=["enter", "tab", "backspace"])
73
+
74
+ p_press = sub.add_parser("press", help="Press a modifier or shortcut combo")
75
+ p_press.add_argument("mod", help="Modifier or combo (shift, ctrl, alt, gui, right, left, f5, 'gui l')")
76
+ p_press.add_argument("ms", nargs="?", type=int, help="Optional hold duration in ms (1-5000)")
77
+
78
+ p_media = sub.add_parser("media", help="Send a Consumer Control media key")
79
+ p_media.add_argument(
80
+ "action",
81
+ choices=["play_pause", "volume_up", "volume_down", "next", "prev", "mute"],
82
+ )
83
+
84
+ p_mouse = sub.add_parser("mouse", help="Control USB HID mouse")
85
+ mouse_sub = p_mouse.add_subparsers(dest="mouse_cmd", required=True)
86
+ pm_move = mouse_sub.add_parser("move", help="Move relative pointer")
87
+ pm_move.add_argument("dx", type=int)
88
+ pm_move.add_argument("dy", type=int)
89
+ pm_click = mouse_sub.add_parser("click", help="Click mouse button")
90
+ pm_click.add_argument("button", choices=["left", "right", "middle"], default="left", nargs="?")
91
+ pm_scroll = mouse_sub.add_parser("scroll", help="Scroll vertical wheel")
92
+ pm_scroll.add_argument("amount", type=int)
93
+
94
+ p_jig = sub.add_parser("jiggler", help="Control mouse jiggler")
95
+ p_jig.add_argument("state", choices=["on", "off", "toggle"])
96
+
97
+ p_macro = sub.add_parser("macro", help="Manage NVS macros (m0..m15)")
98
+ macro_sub = p_macro.add_subparsers(dest="macro_cmd", required=True)
99
+ pm_def = macro_sub.add_parser("define", help="Save macro body to NVS slot")
100
+ pm_def.add_argument("slot", help="Slot name m0..m15")
101
+ pm_def.add_argument("body", help="Command chain to store")
102
+ pm_run = macro_sub.add_parser("run", help="Run stored NVS macro")
103
+ pm_run.add_argument("slot", help="Slot name m0..m15")
104
+
105
+ p_ble = sub.add_parser("ble-name", help="Update BLE advertising name in NVS")
106
+ p_ble.add_argument("name", help="Printable ASCII name (1-29 chars)")
107
+
108
+ p_pk = sub.add_parser("ble-passkey", help="Set 6-digit BLE bonding passkey or 'off'")
109
+ p_pk.add_argument("passkey", help="6-digit passkey (100000-999999) or 'off'")
110
+
111
+ p_lay = sub.add_parser("layout", help="Set USB HID keyboard layout in NVS")
112
+ p_lay.add_argument("name", choices=["us", "tr_q"])
113
+
114
+ p_raw = sub.add_parser("raw-byte", help="Send a single-byte fallback command (e.g. 0x32)")
115
+ p_raw.add_argument("value", help="Hex or decimal byte in 0x10..0x8F")
116
+
117
+ return parser
118
+
119
+
120
+ def main(argv: Optional[list[str]] = None) -> int:
121
+ parser = build_parser()
122
+ args = parser.parse_args(argv)
123
+
124
+ try:
125
+ if args.command == "scan":
126
+ ble_devices = asyncio.run(scan_ble(timeout=args.timeout))
127
+ print("BLE devices (Service 0xFFE0):")
128
+ if ble_devices:
129
+ for addr, name in ble_devices:
130
+ print(f" {addr} {name}")
131
+ else:
132
+ print(" (none)")
133
+ print("Serial ports:")
134
+ ports = list_serial_ports()
135
+ if ports:
136
+ for dev, desc in ports:
137
+ print(f" {dev} {desc}")
138
+ else:
139
+ print(" (none)")
140
+ return 0
141
+
142
+ if args.command == "raw-byte":
143
+ val = int(args.value, 0)
144
+ send_raw_byte(
145
+ val,
146
+ port=args.port,
147
+ address=args.address,
148
+ baud=args.baud,
149
+ timeout=args.timeout,
150
+ )
151
+ print(f"Sent fallback byte 0x{val:02X}")
152
+ return 0
153
+
154
+ wire_cmd = build_command_from_args(args)
155
+ ack = send_command(
156
+ wire_cmd,
157
+ port=args.port,
158
+ address=args.address,
159
+ baud=args.baud,
160
+ timeout=args.timeout,
161
+ seq=args.seq,
162
+ )
163
+ status = "OK" if ack.ok else f"ERR(code={ack.code})"
164
+ print(f"ACK seq={ack.seq} {status}")
165
+ return 0 if ack.ok else 2
166
+ except (ProtocolError, RuntimeError, ValueError, TimeoutError, asyncio.TimeoutError) as exc:
167
+ print(f"Error: {exc}", file=sys.stderr)
168
+ return 1
169
+
170
+
171
+ if __name__ == "__main__":
172
+ raise SystemExit(main())