USBHID-UPS(8)

راهنمای NUT

USBHID-UPS(8)

نام (NAME)

usbhid-ups - درایور برای تجهیزات یوپی‌اس USB/HID

خلاصه دستور (SYNOPSIS)

usbhid-ups -h

usbhid-ups -a UPS_NAME [OPTIONS]

نکته

این صفحه راهنما فقط ویژگی‌های وابسته به سخت‌افزار درایور usbhid-ups را مستند می‌کند. برای اطلاعات بیشتر درباره درایور اصلی، به nutupsdrv(8) مراجعه کنید.

سخت‌افزارهای پشتیبانی‌شده (SUPPORTED HARDWARE)

usbhid-ups قابلیت نظارت بر یوپی‌اس‌های USB/HID را برای NUT در تمام پلتفرم‌هایی که از USB از طریق libusb پشتیبانی می‌کنند فراهم می‌کند. این درایور باید بتواند هر یوپی‌اس استفاده‌کننده از کلاس دستگاه قدرت HID (HID Power Device Class) را شناسایی کند، اما میزان داده‌ها بسته به سازنده و مدل متفاوت خواهد بود.

در حال حاضر، usbhid-ups از موارد زیر پشتیبانی می‌کند:

•مدل‌های USB جدیدتر Eaton،

•تمام مدل‌های USB شرکت MGE،

•تمام مدل‌های USB شرکت Dell،

•تمام مدل‌های AMETEK Powervar UPM،

•برخی مدل‌های APC،

•برخی مدل‌های Belkin،

•برخی مدل‌های Cyber Power Systems،

•برخی مدل‌های Powercom،

•برخی مدل‌های PowerWalker،

•برخی مدل‌های TrippLite.

برای فهرست کامل‌تر، به فهرست سازگاری سخت‌افزاری NUT مراجعه کنید که در توزیع منبع NUT به صورت data/driver.list یا در وب‌سایت NUT در دسترس است.

می‌توانید از گزینه درایور explore برای جمع‌آوری اطلاعات از یوپی‌اس‌های HID که هنوز پشتیبانی نمی‌شوند استفاده کنید تا به افزودن این پشتیبانی کمک شود؛ برای جزئیات به بخش‌های بعد مراجعه کنید.

مشخص شده است که این درایور بر روی سیستم‌های زیر کار می‌کند:

•بیشتر سیستم‌های لینوکس،

•سیستم‌عامل FreeBSD (مرحله بتا) و شاید سایر سامانه‌های *BSD،

•سیستم‌عامل‌های Darwin / Mac OS X،

•سولاریس ۱۰ و توزیع‌های مبتنی بر illumos.

آرگومان‌های اضافی (EXTRA ARGUMENTS)

این درایور همچنین از تنظیمات اختیاری زیر پشتیبانی می‌کند:

port = string

گزینه‌ای الزامی برای تمام درایورهای NUT. مقداری (value) باید مشخص شود، که معمولاً برای درایورهایی که اتصالات USB را مدیریت می‌کنند برابر با auto است.

نکته
این مقدار می‌تواند یک مسیر سیستم‌فایل دستگاه مانند /dev/usb/hiddev0 باشد، اما استفاده کنونی از رابط برنامه‌نویسی (API) مربوط به libusb مانع از شناسایی و تطبیق از طریق چنین شناسه‌هایی می‌شود. همچنین ممکن است آن‌ها ذاتاً غیرقابل اعتماد باشند (وابسته به اتصال مجدد و ترتیب شمارش دستگاه‌ها). در حال حاضر مقدار واقعی (value) نادیده گرفته می‌شود، اما از نظر ساختاری باید مقداری برای پیکربندی port وجود داشته باشد.

کنترل هم‌زمان چندین واحد یوپی‌اس با اجرای چندین نمونه از این درایور امکان‌پذیر است، به شرطی که بتوان با تنظیم ترکیبی از گزینه‌های vendor، product، vendorid، productid، serial، bus و/یا device که در ادامه شرح داده شده‌اند، آن‌ها را به‌طور یکتا متمایز کرد. برای دستگاه‌ها یا سیستم‌عامل‌هایی که اطلاعات کافی ارائه نمی‌دهند، گزینه allow_duplicates می‌تواند مفید باشد (محدود و پرخطر!)

vendorid = regex, productid = regex, vendor = regex, product = regex, serial = regex

انتخاب یک یوپی‌اس مشخص، در صورتی که بیش از یک دستگاه از طریق USB متصل باشد. هر گزینه یک عبارت باقاعده گسترده را مشخص می‌کند (برای اطلاعات بیشتر درباره عبارات باقاعده به regex(7) مراجعه کنید)، که باید با کل مقادیر رشته‌ای مربوطه vendor/product/serial یوپی‌اس (بدون در نظر گرفتن فضاهای خالی اطراف آن) یا کل کد هگزادسیمال ۴ رقمی برای vendorid و productid مطابقت داشته باشد.

اجرای lsusb(8) یا اجرای این درایور NUT با آرگومان خط فرمان -DD را برای پی بردن به رشته‌های مناسب جهت تطبیق امتحان کنید.

مثال‌ها:

•-x vendor="Foo.Corporation.*"

•-x vendorid="051d*" (APC)

•-x product=";.*(Smart|Back)-?UPS.*"

bus = regex

اختیاری، توصیه نمی‌شود.

انتخاب یک یوپی‌اس روی یک گذرگاه (bus) USB خاص یا گروهی از گذرگاه‌ها. این آرگومان یک عبارت باقاعده است که باید با نام گذرگاهی که یوپی‌اس به آن متصل است (مثلاً bus="002" یا bus="00[2-3]") همان‌طور که در لینوکس در /sys/bus/usb/devices یا lsusb(8) مشاهده می‌شود، با احتساب صفرهای ابتدایی مطابقت داشته باشد.

نکته
شماره‌های گذرگاه توسط سیستم‌عامل تضمین نمی‌شوند که در میان راه‌اندازی‌های مجدد سیستم، بارگیری مجدد درایورهای هسته یا اتصال مجدد دستگاه (مانند تغییر وضعیت درگاه‌های هاب USB) پایدار بمانند.

device = regex

اختیاری، توصیه نمی‌شود.

انتخاب یک یوپی‌اس روی یک دستگاه USB خاص یا گروهی از دستگاه‌ها. این آرگومان یک عبارت باقاعده است که باید با نام دستگاهی که یوپی‌اس به آن متصل است (مثلاً device="001" یا device="00[1-2]") همان‌طور که در لینوکس در /sys/bus/usb/devices یا lsusb(8) مشاهده می‌شود، با احتساب صفرهای ابتدایی مطابقت داشته باشد.

نکته
شماره‌های دستگاه توسط سیستم‌عامل تضمین نمی‌شوند که در میان راه‌اندازی‌های مجدد سیستم یا اتصال مجدد دستگاه پایدار بمانند.

busport = regex

اختیاری، توصیه نمی‌شود.

در صورت پشتیبانی سخت‌افزار، سیستم‌عامل و libusb در استقرار مشخص، این گزینه باید اجازه دهد به جای مقادیر منطقی شماره‌گذاری device، شماره درگاه‌های فیزیکی روی یک هاب USB مشخص شوند و در نتیجه — این مورد باید در میان راه‌اندازی‌های مجدد یا اتصال مجدد نوسان کمتری داشته باشد. این مقدار را می‌توان به عنوان مثال در خروجی ساختار USB حاصل از lsusb -tv روی سیستم‌های دارای این ابزار مشاهده کرد.

نکته
این گزینه در عمل توسط برخی ساخت‌های NUT پشتیبانی نمی‌شود (در این صورت باید همراه با یک هشدار نادیده گرفته شود)، و در تمام سیستم‌هایی که NUT می‌تواند روی آن‌ها اجرا شود نیز پشتیبانی نمی‌گردد.

allow_duplicates

اختیاری، توصیه نمی‌شود.

اگر چندین دستگاه یوپی‌اس دارید که ممکن است با گزینه‌های بالا به‌طور یکتا شناسایی نشوند (مثلاً در آنجا فقط VID:PID قابل شناسایی باشد)، این فلگ به هر نمونه درایور که در آن تنظیم شده اجازه می‌دهد نخستین تطابق را در صورت دردسترس بودن برگزیند یا برای بررسی دستگاهی دیگر اقدام کند.

به طور معمول راه‌اندازی درایور در این مرحله با گزارش خطای "Resource busy" یا خطایی مشابه متوقف می‌شود، با این فرض که دستگاهی که به درستی تطبیق یافته یکتا است — و فرآیند دیگری در حال حاضر آن را مدیریت می‌کند.

هشدار
این قابلیت ذاتاً غیرقطعی (non-deterministic) است! انتساب نام نمونه درایور به دستگاه واقعی ممکن است بین دفعات اجرا متفاوت باشد!

اگر فقط برای شما مهم است که بدانید دست‌کم یکی از یوپی‌اس‌های بدون نام شما آنلاین است، این گزینه می‌تواند مفید باشد.

اما اگر واقعاً باید بدانید کدام دستگاه آنلاین است، این گزینه کمکی نخواهد کرد!

usb_set_altinterface = bAlternateSetting

اجبار به فراخوانی مکرر usb_set_altinterface()، به‌ویژه در صورت نیاز برای دستگاه‌هایی با چندین نقش USB که در آن‌ها یوپی‌اس با شماره رابط 0 (پیش‌فرض) نشان داده نمی‌شود.

usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out

اجبار به استفاده از شماره‌های خاص رابط، نقطه انتهایی (endpoint)، شاخص توصیف‌گر و غیره، به جای مقدار پیش‌فرض 0 (به ندرت مقادیر دیگر در درایورهای خاص برای برخی دستگاه‌ها که به استفاده از مقادیر غیرصفر شناخته شده‌اند). به صورت یک عدد هگزادسیمال مشخص می‌شود.

به عنوان یک قاعده کلی برای تشخیص usb_hid_desc_index، می‌توانید مقادیر بزرگ‌تر wDescriptorLength (تقریباً ۶۰۰ بایت به بالا) را در گزارش‌های lsusb یا ابزارهای مشابه مشاهده کنید.

LIBUSB_DEBUG = INTEGER

عیب‌یابی زمان اجرای درایورهای دارای قابلیت USB در NUT نه تنها می‌تواند شامل افزایش سطح جزئیات اشکال‌زدایی معمول NUT باشد (مثلاً با استفاده از تنظیم DEBUG_MIN در ups.conf(5) یا دستورات پروتکل برای تغییر مقدار driver.debug)، بلکه ممکن است از اشکال‌زدایی اختصاصی LibUSB نیز بهره‌مند شود.

برای مورد اخیر، می‌توانید گزینه درایور LIBUSB_DEBUG را تنظیم کنید؛ همچنین می‌توانید به روش سنتی متغیر محیطی LIBUSB_DEBUG را پیش از شروع برنامه درایور NUT (که می‌تواند در اسکریپت راه‌اندازی درایور یا روش سرویس تنظیم و "export" شود، شاید از طریق nut.conf(5))، به یک مقدار عددی مانند 4 ("همه پیام‌ها صادر شوند") تنظیم نمایید.

برای جزئیات بیشتر، از جمله مقادیر پشتیبانی‌شده کنونی برای نسخه کتابخانه شما، به عنوان مثال ببینید:

•https://libusb.sourceforge.io/api-1.0/

•https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html

subdriver=regex

انتخاب زیردرایور USB HID برای دستگاه به صورت دستی، در مواردی که تطبیق خودکار تنها بر اساس ویژگی‌های دستگاه کافی نیست (به عنوان مثال دستگاه‌های جدیدی که هیچ جفت vendorid/productid برای آن‌ها در هیچ درایوری تعبیه نشده است — اما پشتیبانی معمول USB HID برای آن‌ها پیش‌بینی می‌شود، یا برای دستگاه‌هایی با قابلیت‌های متفاوت اما تراشه‌های رابط یکسان، به‌ویژه "phoenixtec/liebert" و "mge").

برنامه درایور را با گزینه --help اجرا کنید تا فهرست دقیق مقادیری از subdriver را که در حال حاضر شناسایی می‌کند، مشاهده نمایید.

نکته
این گزینه ابتدا تطابق‌های دقیق با رشته‌های شناسایی زیردرایور، مانند "TrippLite HID 0.85" (که مستعد کهنگی و عدم تطابق تدریجی هستند) را بررسی می‌کند، و در صورتی که هیچ تطابق دقیقی وجود نداشت — با یک عبارت باقاعده گسترده و بدون حساسیت به بزرگی و کوچکی حروف مجدداً تلاش می‌کند.

نکته
هنگام استفاده از این گزینه، تعیین پارامترهای تطبیق vendorid و productid نیز الزامی است.

lowbatt=num

تنظیم درصدی که در آن یوپی‌اس شارژ باتری را در وضعیت بحرانی ضعیف در نظر می‌گیرد، که احتمالاً منجر به خاموش‌سازی اجباری (FSD) می‌شود.

این مقدار معمولاً توسط دستگاه یوپی‌اس تعیین می‌شود، اگرچه یک مقدار پیش‌فرض جایگزین ۳۰ (به درصد) وجود دارد. بازنویسی این مقدار می‌تواند زمانی مفید باشد که یوپی‌اس این مقدار را روی درصدی کمتر از حد مورد نظر تنظیم می‌کند.

offdelay=num

تنظیم زمان‌سنج (برحسب ثانیه) پیش از خاموش شدن یوپی‌اس پس از ارسال دستور قطع توان (از طریق سوئیچ -k).

مقدار پیش‌فرض ۲۰ (به ثانیه)، یا ۶۰ برای دستگاه‌های CPS است. معمولاً این مقدار باید کمتر از ondelay باشد، اما درایور در هنگام راه‌اندازی در صورتی که چنین نباشد به شما هشدار نخواهد داد.

توجه داشته باشید که بسیاری از مدل‌های Cyber Power Systems (CPS) تمایل دارند این تاخیر را بر ۶۰ تقسیم کرده و رو به پایین گرد کنند، بنابراین حداقل مقدار توصیه‌شده ۶۰ است تا از خاموش شدن فوری پس از ارسال دستور خاموش‌سازی NUT به یوپی‌اس جلوگیری شود. جزئیات بیشتر در ادامه آمده است.

ondelay=num

تنظیم زمان‌سنج (برحسب ثانیه) برای روشن شدن مجدد یوپی‌اس در صورتی که برق پس از ارسال دستور قطع برق، اما پیش از خاموش شدن واقعی بازگردد. این امر تضمین می‌کند که دستگاه‌های متصل به یوپی‌اس در تمام حالات پس از قطع برق راه‌اندازی مجدد شوند.

مقدار پیش‌فرض ۳۰ (به ثانیه)، یا ۱۲۰ برای دستگاه‌های CPS است. معمولاً این مقدار باید بزرگ‌تر از offdelay باشد، اما درایور هنگام راه‌اندازی در صورت عدم رعایت این موضوع به شما هشدار نخواهد داد. برخی از یوپی‌اس‌ها در هر صورت دوباره روشن می‌شوند، حتی اگر برق در لحظه انقضای این تایمر (همچنان) قطع باشد. در این حالت، می‌توانید بررسی کنید که آیا تنظیم ondelay = -1 در ups.conf کمک می‌کند یا خیر.

توجه داشته باشید که بسیاری از مدل‌های CPS تمایل دارند این تاخیر را بر ۶۰ تقسیم کرده و رو به پایین گرد کنند، بنابراین حداقل مقدار توصیه‌شده ۱۲۰ است تا تاخیر کوتاهی بین زمان خاموش شدن یوپی‌اس و بازگشت برق فراهم شود. طبق بیانیه پشتیبانی (حداقل برای برخی مدل‌های CPS)، "سیستم‌های یوپی‌اس ما قادر به تنظیم تاخیر روشن شدن برق نیستند".

pollfreq=num

تنظیم بسامد نظرسنجی برای به‌روزرسانی‌های کامل، برحسب ثانیه. در مقایسه با به‌روزرسانی‌های سریعی که در هر "pollinterval" انجام می‌شوند (گزینه دوم در ups.conf(5) توصیف شده است)، بازه "pollfreq" برای نظرسنجی متغیرهای با اهمیت کمتر است. مقدار پیش‌فرض ۳۰ (برحسب ثانیه)، یا ۱۲ ثانیه برای دستگاه‌های CPS است.

نکته
این تنظیم با گزینه POLLFREQ که توسط upsmon(8) پشتیبانی می‌شود متفاوت است (برای جزئیات به upsmon.conf(5) آن مراجعه کنید).

pollonly

اگر این فلگ تنظیم شود، درایور از انتقال‌های Interrupt In در چرخه‌های کوتاه‌تر "pollinterval" استفاده نخواهد کرد (توصیه نمی‌شود، اما در صورتی که این گزارش‌ها در یوپی‌اس شما با اختلال همراه باشند لازم است).

winhid

اگر این فلگ در ساخت‌های ویندوز تنظیم شود، از بک‌اند آزمایشی بومی Windows HID به جای libusb استفاده می‌شود.

این بک‌اند در حال حاضر یک محدوده متمرکز بر خواندن را دنبال می‌کند. این قابلیت از شناسایی دستگاه و تطبیق از طریق شناسه‌هایی مانند vendorid و productid، خواندن ورودی/ویژگی (input/feature)، و مدیریت جایگزین گزارش وقفه (interrupt-report) پشتیبانی می‌کند. نوشتن گزارش ویژگی در این مرحله پیاده‌سازی نشده است، بنابراین عملیات قابل نوشتن setvar/instcmd ممکن است در دسترس نباشند.

این گزینه در ساخت‌های غیر WIN32 نادیده گرفته می‌شود.

interrupt_pipe_no_events_tolerance=num

تنظیم آستانه تحمل برای اینکه چند بار متوالی می‌توانیم در هنگام استفاده از حالت وقفه USB وضعیت "Got 0 HID objects" را داشته باشیم؟ این وضعیت ممکن است به طور معمول به این دلیل باشد که دستگاه هیچ مورد فوری برای گزارش ندارد، بنابراین مقدار پیش‌فرض -1 است و این وضعیت به هیچ روش خاصی مدیریت نمی‌شود. با این حال در برخی دستگاه‌ها این امر هم‌زمان با یک کنترل‌کننده قفل‌شده (freeze) دیده شد، که تنها اتصال مجدد درایور تبادل داده‌ها را بازیابی کرد (مانند APC BXnnnnMI) — در چنین مواردی ممکن است بخواهید یک مقدار غیرمنفی معقول در اینجا قرار دهید.

onlinedischarge_battery

اگر این فلگ تنظیم شود، درایور وضعیت OL+DISCHRG را به عنوان آفلاین/روی باتری در نظر خواهد گرفت.

برای بیشتر دستگاه‌ها این ترکیب به معنای کالیبراسیون یا اقدامات نگهداری مشابه است؛ با این حال برخی مدل‌های یوپی‌اس (مانند سری CyberPower UT) هنگام قطع برق شهری وضعیت OL+DISCHRG را ارسال می‌کنند — و برای مدیریت خاموش شدن سیستم به این گزینه نیاز دارند.

onlinedischarge

منسوخ‌شده، نام قدیمی برای onlinedischarge_battery که در بالا شرح داده شد.

onlinedischarge_calibration

اگر این فلگ تنظیم شود، درایور وضعیت OL+DISCHRG را به عنوان کالیبراسیون در نظر می‌گیرد. برخی مدل‌های یوپی‌اس (به عنوان مثال مشاهده شده که APC چنین می‌کند) زمانی که در حالت کالیبراسیون هستند وضعیت OL+DISCHRG را گزارش می‌دهند. این وضعیت معمولاً پس از چند ثانیه گزارش حالت OFF نیز رخ می‌دهد، در حالی که سخت‌افزار در حال تغییر وضعیت به حالت روی باتری است.

نکته
اگر این روند در دستگاه شما آن‌قدر طول می‌کشد که دستور خاموش شدن صادر می‌شود، ممکن است بخواهید به گزینه OFFDURATION در upsmon نگاهی بیندازید که برای فیلتر کردن مقادیر موقت "OFF مدیریتی" استفاده می‌شود تا به عنوان قطع تغذیه بار برق‌دار تلقی نگردد.

onlinedischarge_log_throttle_sec=num

تنظیم حداقل بسامد (برحسب ثانیه) که در آن هشدارها برای یک ترکیب وضعیت دستگاه OL+DISCHRG که در غیر این صورت رسیدگی نشده است، صادر می‌شوند. مقادیر منفی پیام‌های تکراری متوالی را (زمانی که این حالت ظاهر می‌شود و باقی می‌ماند) غیرفعال می‌کنند.

اگر دستگاه متغیر battery.charge را گزارش نکند، مقدار پیش‌فرض ۳۰ ثانیه است (کاملاً مکرر، در صورتی که ترکیب وضعیت گزارش‌شده توسط یوپی‌اس نشان‌دهنده وضعیت بد برق باشد و در نتیجه شرایط اضطراری تلقی شود).

اگر متغیر battery.charge را گزارش کند، به طور پیش‌فرض اعلان‌های تکراری تنها در صورتی ثبت می‌شوند که این میزان شارژ با زمان صدور پیام قبلی متفاوت باشد (به عنوان مثال هنگامی که باتری واقعاً در حال تخلیه است).

اگر هم این گزینه تنظیم شده باشد و هم battery.charge به درستی گزارش شود، هر یک از این قوانین اجازه ثبت اعلان را می‌دهند.

onlinedischarge_log_throttle_hovercharge=num

جزئیات را در توضیحات onlinedischarge_log_throttle_sec و محدودسازی ثبت پیام لاگ بر اساس battery.charge در بالا ببینید. این گزینه مفهوم "شناورسازی" (hovering) شارژ باتری یوپی‌اس را در سطحی که برای ساختار شیمیایی آن ایمن تلقی می‌شود و عدم اجبار به شارژ کامل مداوم آن اضافه می‌کند. تا زمانی که مقدار فعلی battery.charge در این درصد آستانه (پیش‌فرض ۱۰۰) یا بالاتر از آن باقی بماند، ثبت پیام OL+DISCHRG توسط نوسانات شارژ تحریک نمی‌شود.

lbrb_log_delay_sec=num

تنظیم برای تاخیر در تعیین وضعیت (و پیام‌های لاگ) درباره ورود دستگاه به حالت LB یا LB+RB.

برخی مدل‌های دستگاه یا نسخه‌های میان‌افزار APC BXnnnnMI (طبق گزارش‌ها ۲۰۲۳-۲۰۲۴)، یا مدل‌های دستگاه APC BVKnnnnM2، یا APC BKnnnnM2-CH (مدلی فقط برای بازار چین)، غالباً حالت‌های "باتری ضعیف است" (low battery)، "تعویض باتری" (replace battery)، و "همه چیز خوب است" (all ok) را به طور مکرر و به سرعت در عرض چند ثانیه تغییر می‌دهند، که گاهی (اما نه همیشه) پیش از آن OL+DISCHRG (احتمالاً کالیبراسیون) رخ می‌دهد.

این تنظیم به درایور اجازه می‌دهد از حالت‌های زودگذر چشم‌پوشی کند و تنها در صورتی به آن‌ها توجه کند که مدت بیشتری نسبت به این تنظیم ادامه یابند (و وضعیت توان دستگاه OL باشد).

lbrb_log_delay_without_calibrating

تنظیم برای اعمال lbrb_log_delay_sec حتی اگر دستگاه در حال کالیبراسیون نباشد.

disable_fix_report_desc

تنظیم برای غیرفعال کردن اصلاحات رمزگذاری خراب USB و غیره، که ما به طور پیش‌فرض روی برخی مدل‌ها (سازندگان/محصولات) که گزارش شده پروتکل را به دقت رعایت نمی‌کنند، اعمال می‌کنیم. این فلگ اجازه می‌دهد این قابلیت در پیکربندی‌های خاص دستگاه غیرفعال شود.

همواره این احتمال وجود دارد که سازندگان در نهایت میان‌افزار اصلاح‌شده را منتشر کنند، یا شناسه‌هایی را که ما برای تطبیق دستگاه‌های مشکوک به خرابی استفاده می‌کنیم برای محصولات نامرتبط دیگری استفاده مجدد کنند، بنابراین پردازش این اصلاحات در آنجا اتلاف وقت خواهد بود.

همچنین همواره این احتمال وجود دارد که اصلاحات NUT به دلیل باگ‌های NUT یا به این دلیل که پیاده‌سازی پروتکل توسط سازنده در بیش از یک مکان معیوب است، در برخی دستگاه‌ها مشکلاتی ایجاد کند.

powercom_sdcmd_byte_order_fallback

کد اولیه زیردرایور PowerCOM HID (تا نسخه ۰.۷) دستورات shutdown و stayoff یوپی‌اس را با ترتیب بایت نادرست نسبت به آنچه دستگاه‌های واقعی موجود در بازار در سال ۲۰۲۴ نیاز داشتند، ارسال می‌کرد. ترتیب بایت از نسخه ۰.۷۱ به بعد برای پاسخگویی به دستگاه‌های جدید به طور پیش‌فرض اصلاح شده است. صرفاً در صورتی که میان‌افزارهای متفاوتی با رفتارهای معکوس وجود داشته باشند، ما این سوئیچ را برای استفاده از رفتار قدیمی در یک استقرار مشخص فراهم کرده‌ایم. شاید این فقط یک باگ بوده و هیچ‌کس به این حالت جایگزین احتیاج نداشته باشد...

powercom_sdcmd_discrete_delay

برخی دستگاه‌ها (سری‌های Raptor و Smart KING Pro) از پروتکلی پیروی می‌کنند که در آن نمی‌توانیم مقدار دلخواهی برای تاخیر خاموش شدن برحسب ثانیه (مانند سایر یوپی‌اس‌های powercom) تعیین کنیم، بلکه باید فقط از مقادیر مشخص‌شده در "جدول تاخیرهای ممکن برای دستورات خاموش‌سازی" در سند پروتکل استفاده کنیم. این گزینه باعث می‌شود درایور تاخیرها را بین ثانیه‌ها (در متغیرهای استاندارد NUT) و نزدیک‌ترین ورودی نمایه‌شده از آن جدول تبدیل کند.

explore

با این گزینه، درایور به هر دستگاهی، از جمله دستگاه‌هایی که هنوز پشتیبانی نمی‌شوند، متصل خواهد شد. این گزینه باید همیشه با گزینه "vendorid" ترکیب شود. در این حالت، درایور هیچ کار مفیدی به جز چاپ اطلاعات اشکال‌زدایی (معمولاً همراه با -DD) انجام نخواهد داد.

maxreport

با این گزینه، درایور ترفندی را برای دور زدن میان‌افزارهای معیوب که طول گزارش HID نامعتبر برمی‌گردانند، فعال می‌کند. برخی از دستگاه‌های APC Back-UPS به داشتن این باگ شناخته شده‌اند.

interruptonly

اگر این فلگ تنظیم شود، درایور از یوپی‌اس نظرسنجی (poll) نخواهد کرد. این امر همچنین مستلزم استفاده از اشیاء با نشانگر INPUT است. برخی از دستگاه‌های Powercom به این گزینه نیاز دارند.

interruptsize=num

محدود کردن تعداد بایت‌های خوانده‌شده از خط لوله وقفه (interrupt pipe). برای برخی از دستگاه‌های Powercom این گزینه باید برابر با ۸ باشد.

waitbeforereconnect=num

درایور در صورت بروز خطای غیرمنتظره به طور خودکار تلاش می‌کند دوباره به یوپی‌اس متصل شود. این پارامتر (برحسب ثانیه) به آن اجازه می‌دهد پیش از اقدام به اتصال مجدد منتظر بماند. مقدار پیش‌فرض ۰ است.

نکته
به عنوان مثال، مشخص شد که میان‌افزار یوپی‌اس Eaton MGE Ellipse Max 1500 FR هر چند ساعت یک‌بار پاسخ‌دهی را متوقف می‌کند، که باعث می‌شود درایور usbhid-ups خطای حافظه ناکافی libusb را تشخیص دهد؛ در این حالت، هنگامی که درایور usbhid-ups خیلی زود تلاش می‌کند دوباره متصل شود، این فعالیت گاهی اوقات منجر به خرابی (crash) میان‌افزار یوپی‌اس و خاموش شدن فوری بار متصل می‌شد! تنظیم این پارامتر روی ۳۰ ثانیه این مشکل را حل کرد (در حالی که ۲۰ ثانیه کافی نبود).

نصب (INSTALLATION)

این درایور ممکن است به طور پیش‌فرض ساخته نشود. می‌توانید با نصب پیش‌نیازها و استفاده از configure --with-usb=yes آن را بسازید. توجه داشته باشید که این کار سایر درایورهای USB را نیز نصب خواهد کرد.

همچنین برای رفع مشکل تنظیمات مجوز دسترسی، باید فایل‌های قدیمی hotplug (شامل libhidups و libhid.usermap، عموماً در /etc/hotplug/usb/) یا فایل udev (شامل nut-usbups.rules، عموماً در /etc/udev/rules.d/) را به صورت دستی نصب کنید. برای اطلاعات بیشتر، به فایل‌های scripts/hotplug/README.adoc یا scripts/udev/README.adoc در منابع NUT مراجعه فرمایید.

پیاده‌سازی (IMPLEMENTATION)

انتخاب یک یوپی‌اس خاص (Selecting a specific UPS)

همان‌طور که در بالا ذکر شد، این درایور مقدار "port" در ups.conf را نادیده می‌گیرد.

برخلاف نسخه‌های پیشین این درایور، اکنون کنترل چندین واحد یوپی‌اس به طور هم‌زمان با نمونه‌هایی از این درایور که به صورت موازی اجرا می‌شوند امکان‌پذیر است، به شرطی که بتوان با تنظیم ترکیبی از گزینه‌های تطبیق دستگاه، آن‌ها را متمایز کرد.

به عنوان مثال:

[mge]
        driver = usbhid-ups
        port = auto
        vendorid = 0463
[tripplite]
        driver = usbhid-ups
        port = auto
        vendorid = 09ae

برای نظارت بر دستگاه‌هایی که از شناسه سازنده و محصول یکسان استفاده می‌کنند (مانند دو دستگاه از یک مدل)، باید معیارهای تطبیق یکتای قابل اعتمادی بیابید:

•شماره سریال (serial)، در صورت وجود، بهترین گزینه است.

•شناسه‌های سطح پیوند bus/device/busport ممکن است غیرقابل اعتماد باشند (به دلیل شماره‌گذاری مجدد ناگهانی توسط سیستم‌عامل).

•اگر هیچ چیز دیگری کمک نکرد، گزینه allow_duplicates ممکن است در برخی موارد یک راهکار باشد.

نظرسنجی USB و انتقال‌های وقفه (USB Polling and Interrupt Transfers)

درایور usbhid-ups دارای دو بازه زمانی نظرسنجی (polling) است. گزینه پیکربندی "pollinterval" چیزی را که می‌توان "حلقه درونی" در نظر گرفت کنترل می‌کند، جایی که درایور نظرسنجی را انجام داده و مدت کوتاهی برای گزارش‌های "وقفه" (interrupt) منتظر می‌ماند. گزینه "pollfreq" برای به‌روزرسانی‌های با تناوب کمتر برای مجموعه بزرگ‌تری از مقادیر است، و به همین دلیل، ما توصیه می‌کنیم آن بازه را چندین برابر مقدار "pollinterval" تنظیم کنید.

بسیاری از یوپی‌اس‌ها به انتقال USB Interrupt In با گزارش‌های HID مربوط به مقادیری که تغییر کرده‌اند پاسخ می‌دهند. این کار درایور را از نظرسنجی تک‌تک مقادیر با انتقال‌های USB Control بی‌نیاز می‌کند. از آنجا که فلگ‌های وضعیت OB و LB برای خاموش شدن تمیز سیستم حیاتی هستند، درایور همچنین مسیرهای HID مربوط به آن بیت‌های وضعیت را در طول دوره زمانی درون "pollinterval" به صراحت نظرسنجی می‌کند. در صورتی که مشخص باشد انتقال‌های Interrupt In کار نمی‌کنند، می‌توان از گزینه "pollonly" برای صرف‌نظر کردن از آن‌ها استفاده کرد.

مشکلات و باگ‌های شناخته‌شده (KNOWN ISSUES AND BUGS)

یوپی‌اس مقدار ۶۵۵۳۵ ثانیه (یا ۱۸:۱۲:۱۵) را برای قابلیت battery.runtime گزارش می‌دهد (UPS reports 65535 sec (or 18:12:15) of battery.runtime capability)

بر اساس تعدادی از گزارش‌ها، به نظر می‌رسد که برخی از دستگاه‌ها یا نمی‌توانند بیش از یک مقدار ۱۶ بیتی بدون علامت را در فیلد استاندارد زمان کارکرد باقی‌مانده گزارش دهند (فیلدهای توسعه‌یافته سازنده ممکن است وجود داشته باشند اما در جدول‌های نگاشت ساخت کنونی درایور NUT شما ناشناخته باشند)، یا برای خطا مقدار -۱ را برمی‌گردانند و با آن به عنوان یک مقدار ۱۶ بیتی بدون علامت ۶۵۵۳۵ رفتار می‌شود.

طبق برخی بحث‌های مطرح‌شده در گزارش مشکلات، گذراندن یک آزمایش باتری (کالیبراسیون) می‌تواند به یوپی‌اس در تخمین مجدد و صحیح‌تر زمان کمک کند.

این مشکل همچنین ممکن است به یک یوپی‌اس با ظرفیت بالا که بار بسیار کمی به آن متصل است مرتبط باشد. در برخی موارد، مستندات سازنده به صراحت بیان می‌کند که محاسبه زمان اجرا با بارهای کمتر از مثلاً ۱۰٪ قابل اعتماد نیست.

وقفه زمانی و کهنگی مکرر (Repetitive timeout and staleness)

برخی مدل‌ها با بسامد نظرسنجی پیش‌فرض تمایل به عدم پاسخ‌دهی دارند. در نتیجه لاگ سیستم شما حاوی پیام‌های متعددی مانند این خواهد بود:

usb 2-1: control timeout on ep0in
usb 2-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid-ups rqt 128 rq 6 len 256
ret -110

در این حالت، به سادگی پارامتر عمومی "pollinterval" را به مقدار بالاتری (مانند ۱۰ ثانیه) تغییر دهید. این کار باید مشکل را برطرف کند.

توجه داشته باشید که اگر "pollinterval" را به بیش از ۱۰ یا ۱۵ ثانیه افزایش دادید، ممکن است بخواهید "pollfreq" را نیز با همان ضریب افزایش دهید.

با برخی دستگاه‌ها و سیستم‌عامل‌ها، به ویژه شناسه سازنده USB متعلق به MGE/Eaton یعنی (0x0463) در برخی نسخه‌های هسته لینوکس، ممکن است با برهم‌کنش ضعیف سازوکار "USB HID quirk" مواجه شوید، که مانع از این می‌شود که لینوکس ابتدا دستگاه را به عنوان یک hid-generic ببیند تا بعداً آن را به یک درایور NUT واگذار کند. برای جزئیات بیشتر، به سند پرسش‌های متداول (FAQ) در NUT مراجعه فرمایید. این ویژگی رفتاری خاص را می‌توان با یک پارامتر بوت هسته (از طریق GRUB و غیره) تنظیم کرد:

usbhid.quirks=0x0463:0xffff:0x08

برعکس، برخی از کنترل‌کننده‌های سخت‌افزاری ممکن است در صورت عدم برقراری تماس برای مدتی طولانی "به خواب بروند"؛ دستگاه‌های CPS معمولاً چنین رفتاری دارند. در این حالت، فعال کردن فلگ pollonly و/یا کوچک نگه داشتن pollfreq و/یا pollinterval را مد نظر قرار دهید.

دریافت خطای EPERM: Operation not permitted در زمان شروع به کار درایور (Got EPERM: Operation not permitted upon driver startup)

شما فراموش کرده‌اید فایل‌های hotplug را همان‌طور که در بخش نصب در بالا توضیح داده شد، نصب کنید. فراموش نکنید که hotplug را مجدداً راه‌اندازی نمایید تا این تغییرات اعمال شوند.

خاموش‌سازی‌های بدون نظارت (Unattended shutdowns)

سخت‌افزاری که برای توسعه این درایور استفاده شده است مطمئناً با آنچه شما دارید متفاوت است، و همه سازندگان مشخصات USB HID Power Device Class را مو به مو رعایت نمی‌کنند. مسلماً نمی‌خواهید زمانی که قطعی برق به اتاق سرور شما می‌رسد و برای راه‌اندازی دستی سرورهایتان در محل حضور ندارید، متوجه شوید دستگاه شما در این زمینه مشکلاتی دارد.

اگر برای خاموش کردن سیستم‌هایتان در صورت قطعی برق اصلی و راه‌اندازی مجدد آن‌ها پس از بازگشت برق به یوپی‌اس متکی هستید، باید این مورد را آزمایش کنید. می‌توانید این کار را با اجرای دستور upsmon -c fsd انجام دهید. در حضور برق اصلی، این کار باید سیستم‌های شما را خاموش کرده و سپس برق را قطع و وصل کند تا مجدداً راه‌اندازی شوند. اگر همین کار را بدون وجود برق اصلی انجام دهید، باید همین روال طی شود، با این تفاوت که در این حالت خروجی‌ها باید تا زمان برقراری مجدد برق اصلی خاموش بمانند.

یوپی‌اس برق را خیلی زود قطع می‌کند (UPS cuts power too soon)

توجه داشته باشید که بسیاری از مدل‌های Cyber Power Systems (CPS) تمایل دارند offdelay را بر ۶۰ تقسیم کرده و رو به پایین گرد کنند، بنابراین حداقل مقدار توصیه‌شده ۶۰ (ثانیه) است تا از خاموش شدن فوری پس از ارسال دستور خاموش‌سازی NUT به یوپی‌اس جلوگیری شود.

برای بسیاری از یوپی‌اس‌های Cyberpower، جهت رفتار عادی (بازیابی بار متصل هنگام بازگشت برق متناوب AC) مقدار offdelay باید برابر با ۰ تنظیم شود. تنظیم offdelay بالاتر از ۰ باعث راه‌اندازی مجدد بار یوپی‌اس بدون توجه به اینکه آیا برق بازگشته است یا خیر خواهد شد، و تنظیم offdelay به کمتر از ۰، عملکرد روشن شدن خودکار یوپی‌اس را غیرفعال می‌کند و بار حتی با بازگشت برق خاموش باقی می‌ماند.

یوپی‌اس متغیر battery.charge.low را تنظیم نمی‌کند اما وضعیت OK را اعلام می‌کند (UPS does not set battery.charge.low but says OK)

توجه داشته باشید که بسیاری از مدل‌های Cyber Power Systems (CPS) تمایل دارند تنها مقادیر خاصی را برای battery.charge.low مجاز بدانند و هر مقداری خارج از مجموعه مقادیر مجاز گرد شده یا نادیده گرفته می‌شود.

یک حلقه پوسته مانند زیر می‌تواند به شما کمک کند مقادیر مجاز را شناسایی کنید:

for i in `seq 90 -1 0`; do echo "set to $i"; \
    upsrw -s battery.charge.low=$i -u * -p * cps-big; \
    sleep 1; upsc cps-big battery.charge.low; echo ""; \
done

به عنوان مثال، برای مدل CPS PR1000LCDRTXL2U تنها مقادیر مجاز [60,55,50,45,40,35,30,25,20] هستند و در برخی موارد، یوپی‌اس شما عملاً ممکن است از مقدار ۱۰ برای تنظیم battery.charge.low پشتیبانی نکند.