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 ٹیگز۔ ### لاگنگ اس پیکیج میں لاگ فائل اپ لوڈ یا `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 کے ذریعے جڑتا ہے، جس سے کم تاخیر والی ٹیلی میٹری اسٹریم اور ڈیش بورڈ سے متحرک اعمال لے جانے والا چینل ملتا ہے۔ ساکٹ دستیاب نہ ہونے پر شفاف طور پر `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 پیکیج کے ساتھ تین skills شامل ہیں، جو کوڈنگ ایجنٹس کو 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۔