plexus-python

## अवलोकन plexus-python, Plexus प्लेटफ़ॉर्म का हल्का Python SDK है। Plexus हार्डवेयर टीमों को टाइम-सीरीज़ डेटा स्टोरेज और डैशबोर्ड प्रदान करता है: ड्रोन, रोबोट, IoT डिवाइस का डेटा Plexus Time Series में स्ट्रीम करें, या मौजूदा डेटाबेस से जोड़ें, और रीयल-टाइम डैशबोर्ड व अलर्ट पाएं। यह पैकेज केवल डेटा को Plexus गेटवे तक पहुंचाने का काम करता है; स्टोरेज, डैशबोर्ड, अलर्ट और फ़्लीट प्रबंधन प्लेटफ़ॉर्म की ओर होते हैं। ## त्वरित शुरुआत ```bash pip install plexus-python ``` ```python from plexus import Plexus px = Plexus(api_key="plx_xxx", source_id="device-001") px.send("temperature", 72.5) ``` API key app.plexus.company/api पर मिल सकती है, या `plexus init` चलाकर ब्राउज़र में इस मशीन को अधिकृत करें। ## डिवाइस पहचान हर डिवाइस को एक अद्वितीय `source_id` चाहिए। इसे सेटअप स्क्रिप्ट से सेट करने की सलाह दी जाती है, जिसमें पहले डिवाइस का नाम देना होता है: ```bash curl -sL https://app.plexus.company/setup | bash -s -- \ --key plx_xxx --name drone-01 ``` नाम को डिवाइस के `source_id` में बदला जाता है, जिसे `^[a-z0-9][a-z0-9._-]*$` से मेल खाना चाहिए (अधिकतम 256 अक्षर)। अगर न `--name` दिया गया हो और न कोड में `source_id=...`, तो SDK पहली बार चलने पर एक रैंडम id (जैसे `source-1a2b3c4d`) बनाकर `~/.plexus/config.json` में सहेज देता है। होस्टनेम का उपयोग न करें: क्लोन किए गए SD कार्ड इमेज सभी `raspberrypi` के रूप में बूट होते हैं, और टेलीमेट्री एक ही source में मिल जाएगी। नाम अपने आप डीडुप्लिकेट नहीं होते; गेटवे घोषित `source_id` को जैसा है वैसा ही लौटाता है, इसलिए दो डिवाइस एक ही नाम घोषित करें तो वे एक ही source में लिखेंगे। ## मुख्य मेथड ### send(metric, value) सबसे अधिक उपयोग होने वाला मेथड, हर नई रीडिंग पर कॉल करें। `metric` एक डॉट-सेपरेटेड नेमस्पेस स्ट्रिंग है (जैसे `"motor.rpm"`), और `value` किसी भी JSON-सीरियलाइज़ेबल टाइप को स्वीकार करता है: float/int (सेंसर रीडिंग, काउंटर), str (स्टेट मशीन, एरर कोड), bool (बाइनरी फ़्लैग), dict (वेक्टर, संरचित रीडिंग), list (वेवफ़ॉर्म, जॉइंट एंगल)। वैकल्पिक पैरामीटर `tags={"motor_id": "A1"}` डैशबोर्ड फ़िल्टरिंग के लिए, और `timestamp=t` Unix सेकंड-स्तरीय टाइमस्टैम्प निर्दिष्ट करने के लिए। ### send_batch(points) एक साथ कई रीडिंग भेजें, जो टाइमस्टैम्प साझा करती हैं और एक ही नेटवर्क कॉल में मर्ज हो जाती हैं। `points` `(metric, value)` ट्यूपल की सूची है, या प्रति-पॉइंट टाइमस्टैम्प चाहिए तो `(metric, value, timestamp)` ट्रिपल की। ### batch() जब प्रति सेकंड कुछ रीडिंग से अधिक हों तो उपयोग करें। हर `send()` एक WebSocket संदेश है, और गेटवे संदेशों की संख्या सीमित करता है, पॉइंट्स की नहीं (प्रति कनेक्शन 2,000/s)। 25 चैनल 100 Hz पर एक-एक करके भेजने का मतलब 2,500 संदेश/s, और ओवरफ़्लो स्टोरेज से पहले ड्रॉप हो जाता है। ```python with px.batch(interval_ms=50) as b: while running: b.send("att.pos_x", att.x) ``` बैकग्राउंड थ्रेड हर `interval_ms` पर क्यू फ़्लश करता है, ब्लॉक छोड़ते समय बचा डेटा फ़्लश होता है, और रीडिंग अपने कैप्चर समय के टाइमस्टैम्प बनाए रखती हैं। अगर गेटवे फ़्रेम ड्रॉप करता है तो `RATE_LIMITED` रिपोर्ट होता है, SDK `px.rate_limited_frames` में गिनता है और अगली बार भेजते समय `RateLimitedError` थ्रो करता है। ### run(name) run, source पर एक नामित समय-विंडो है, जिसे `/runs` में दोबारा देखा जा सकता है, T+0 पर अलाइन करके तुलना की जा सकती है, और बंद होने पर पास मानदंड के अनुसार जांचा जा सकता है। ब्लॉक छोड़ने पर run को `completed` चिह्नित किया जाता है, अपवाद होने पर `aborted` और फिर से थ्रो किया जाता है। `px.start_run()` / `px.end_run()` अलग-अलग भी कॉल कर सकते हैं, `end_run()` `test_result` वाला run लौटाता है। ### event(name, data) "क्या हुआ" को रिकॉर्ड करने के लिए, न कि "लगातार मापी जाने वाली मात्रा" को: फ़ॉल्ट, स्टेट स्विच, ऑपरेटर क्रियाएं, लॉग एंट्री। प्लेटफ़ॉर्म इवेंट को टेलीमेट्री ग्राफ़ पर टाइम-सीरीज़ लाइन के बजाय मार्कर के रूप में दिखाता है। एकल इवेंट सीमाएं: स्ट्रिंग मान 256 बाइट, dict/list मान 4,096 बाइट JSON, अधिकतम 16 tag। ### लॉग इस पैकेज में लॉग फ़ाइल अपलोड या `logging.Handler` नहीं है। अहम लॉग लाइनें Plexus में भेजने के लिए इवेंट का उपयोग करें: `px.event("log", {"level": "error", "msg": "..."})`। केवल वही लाइनें अग्रेषित करें जो टाइमलाइन पर दिखनी चाहिए (एरर, वॉर्निंग, स्टेट बदलाव), हर डीबग लॉग न भेजें। ## वीडियो स्ट्रीमिंग वीडियो के लिए पेड प्लान चाहिए: फ़्रेम WebSocket से जाते हैं, फ़्री प्लान में गेटवे मना कर देता है। फ़्रेम रीयल-टाइम में दर्शकों तक अग्रेषित होते हैं, और केवल ऐप में Record दबाने पर स्टोर होते हैं, एक रिकॉर्डिंग अधिकतम 4 घंटे। - `send_video_frame(frame, camera_id)`: जब आप खुद कैप्चर लूप संभालते हैं (picamera2 कॉलबैक, OpenCV VideoCapture लूप, स्व-प्रबंधित FFmpeg पाइप)। numpy ndarray स्वीकार करता है (opencv-python चाहिए), JPEG बाइट्स (जैसा है वैसा पास), अन्य इमेज बाइट्स (Pillow से डिकोड और JPEG में री-एनकोड, `pip install plexus-python[video]` चाहिए)। - `stream_camera(url, camera_id)`: जब RTSP स्ट्रीम या वीडियो फ़ाइल हो और कैप्चर लूप खुद नहीं संभालना हो, SDK अंदर से FFmpeg चलाता है (FFmpeg `$PATH` में चाहिए)। `threading.Event` लौटाता है, `.set()` कॉल करके रोकें, बैकग्राउंड थ्रेड में चलता है। ## अपना प्रोटोकॉल लाएं इस पैकेज में एडाप्टर, ऑटो-डिटेक्शन या डेमन नहीं है, केवल क्लाइंट है। जिन लाइब्रेरी का आप पहले से उपयोग करते हैं, उनसे मान `px.send()` में भेजें; README में MAVLink (pymavlink), CAN (python-can), MQTT (paho-mqtt), I2C सेंसर (Adafruit CircuitPython) के उदाहरण हैं, और `examples/` में चलने योग्य संस्करण हैं। ## विश्वसनीयता हर भेजने से पहले डेटा लोकल बफ़र होता है, फिर नेटवर्क पर जाता है, एक्सपोनेंशियल बैकऑफ़ रीट्राई के साथ, और नेटवर्क कटने पर भी डेटा बचा रहता है। बफ़र डिफ़ॉल्ट रूप से डिस्क (SQLite) पर होता है, जो रीस्टार्ट और पावर कट के बाद भी बचा रहता है; `persistent_buffer=False` पर केवल मेमोरी में। `px.buffer_size()` और `px.flush_buffer()` से पॉइंट्स की संख्या देखें और फ़्लश करें। ## टाइमस्टैम्प और क्लॉक करेक्शन डिफ़ॉल्ट रूप से SDK खुद समय चुनता है। WebSocket पर हर कनेक्शन पर गेटवे क्लॉक से सिंक होता है, इसलिए डिवाइस का सिस्टम क्लॉक गलत होने पर भी (पहली बूट में NTP नहीं, RTC एक्सपायर, नई सिस्टम इमेज) डेटा टाइमलाइन पर सही जगह पड़ता है। भरोसेमंद बाहरी समय स्रोत (GPS, विश्वसनीय RTC, होस्ट NTP) हो या ज्ञात टाइमस्टैम्प वाला ऐतिहासिक डेटा रीप्ले करना हो, तो स्पष्ट रूप से `timestamp` पास करें। ज्ञात सीमाएं: क्लॉक सिंक WebSocket रीकनेक्ट पर रीफ़्रेश होता है, लंबे कनेक्शन और RTC ड्रिफ्ट वाले डिवाइस रीकनेक्ट अंतराल तक अनकरेक्टेड ड्रिफ्ट जमा करते हैं; HTTP फ़ॉलबैक पथ क्लॉक सिंक नहीं लेता; `send_batch()` डिफ़ॉल्ट रूप से एक टाइमस्टैम्प साझा करता है। ## ट्रांसपोर्ट डिफ़ॉल्ट रूप से गेटवे के `/ws/device` पर WebSocket से कनेक्ट होता है, जिससे कम विलंबता वाली टेलीमेट्री स्ट्रीम और डैशबोर्ड-ट्रिगर क्रियाओं के लिए चैनल मिलता है। socket उपलब्ध न होने पर पारदर्शी रूप से `POST /ingest` पर फ़ॉलबैक होता है, डेटा नहीं खोता। कोई ट्रांसपोर्ट सेलेक्टर नहीं है, SDK हमेशा WebSocket को प्राथमिकता देता है। फ़्री प्लान में गेटवे डिवाइस WebSocket मना करता है (`streaming_requires_plan`), SDK खुद HTTP पर फ़ॉलबैक करता है, `send()`、`send_batch()`、`batch()`、`event()` अभी भी काम करते हैं; रीयल-टाइम स्ट्रीम और वीडियो के लिए पेड प्लान चाहिए, फ़्री प्लान में 3 डिवाइस और 7 दिन का इतिहास सीमित है। ## कमांड आप घोषित कर सकते हैं कि कोड कौन-कौन से कमांड स्वीकार करता है, यह पहले `send()` से पहले घोषित करना होता है (घोषणा ऑथ फ़्रेम के साथ भेजी जाती है)। `@px.command(...)` से हैंडलर डेकोरेट करें, पैरामीटर string (maxLength, enum), integer/number (minimum, maximum, unit), boolean का समर्थन करते हैं, साथ में title, description, default, required, अधिकतम 16 और सपाट बिना नेस्टिंग। `danger` normal/dangerous/critical होता है, `idempotent` सत्य होने पर डिस्कनेक्ट के बाद ही दोबारा भेजा जाता है, `expires_in` 5–3600 सेकंड, `concurrency` वैकल्पिक accept/reject। हैंडलर `handler(run, **params)` के रूप में कॉल होता है, पैरामीटर पहले से वैलिडेट और कन्वर्ट होते हैं, रिटर्न मान run परिणाम बनता है, अपवाद run को `failed` कर देता है। Receive commands अनुमति वाली API key चाहिए। SDK हर run को स्वीकार करता है, एक ही run id दोबारा नहीं चलाता, मोनोटोनिक क्लॉक से एक्सपायरी तय करता है, और रीकनेक्ट के बाद अनकन्फर्म्ड स्टेट रीप्ले करता है। `px.on_command()` अब अप्रचलित है पर पुराने सिग्नेचर के साथ अभी भी काम करता है। ## एनवायरनमेंट वेरिएबल `PLEXUS_API_KEY` (आवश्यक), `PLEXUS_GATEWAY_URL` (डिफ़ॉल्ट `https://gateway.plexus.company`), `PLEXUS_GATEWAY_WS_URL` (डिफ़ॉल्ट `wss://gateway.plexus.company`)। ## Agent skills पैकेज के साथ तीन skill आते हैं, जो कोडिंग एजेंट को Plexus API का उपयोग सिखाते हैं (एंडपॉइंट, रीयल-टाइम स्ट्रीम, साइलेंट 400 देने वाली सामान्य गलतियां)। `plexus skills install` से `~/.claude/skills` में इंस्टॉल होता है, `--project` जोड़ने पर `./.claude/skills` में इंस्टॉल होता है और रेपो के साथ चलता है। शुद्ध Markdown, कोई इंस्टॉलेशन या क्रेडेंशियल नहीं चाहिए। ## आर्किटेक्चर ``` Your code ── px.send() ── WebSocket /ws/device (या HTTP POST /ingest) ──> plexus-gateway ──> ClickHouse + Dashboard ``` एक हल्का पथ, कोई agent नहीं, कोई डेमन नहीं, कोई एडाप्टर नहीं। पूरा HardwareOps प्लेटफ़ॉर्म (डैशबोर्ड, अलर्ट, RCA, फ़्लीट व्यू) app.plexus.company के Web UI में है। ## लाइसेंस Apache 2.0।