APC_MODBUS(8) NUT Manual APC_MODBUS(8)

apc_modbus - درایور پروتکل مادباس برای APC Smart-UPS

apc_modbus -h

apc_modbus -a UPS_NAME [OPTIONS]

به‌طور کلی این درایور باید برای تمام دستگاه‌های UPS مادباس APC کار کند. برخی دستگاه‌ها ممکن است اطلاعات بیشتری نسبت به آنچه در حال حاضر پشتیبانی می‌شود، مانند چند فاز بودن، ارائه دهند. یک قاعده کلی تجربی این است که دستگاه‌های APC (یا نسخه‌های سفت‌افزار) عرضه‌شده پس از سال ۲۰۱۰، به احتمال بیشتری از استاندارد USB HID، از مادباس پشتیبانی می‌کنند.

با سخت‌افزارهای زیر آزمایش شده است:

•SMT1500 (Smart-UPS 1500, Firmware 9.6)
•SMX750 (Smart-UPS X 750, Firmware 10.1)
•SMX1500 (Smart-UPS X 1500, Firmware 15.0)
•SMX2200 (Smart-UPS X 2200, Firmware 15.0)

توجه داشته باشید که باید ارتباط مادباس را فعال کنید. در پنل جلویی UPS، به حالت منوی پیشرفته (Advanced Menu) بروید، زیر بخش Configuration گزینه Modbus را فعال کنید.


نکته

این درایور با رابط‌های سریال، TCP و USB برای مادباس آزمایش شده است. شایان ذکر است که امروزه پورت‌های سریال روی همه دستگاه‌ها در دسترس نیستند؛ پشتیبانی از TCP ممکن است نیازمند خرید یک کارت مدیریت شبکه اضافی باشد؛ و پشتیبانی از USB در حال حاضر نیازمند ساخت غیراستاندارد libmodbus (یک pull request در مخزن بالادستی کتابخانه در زمان انتشار این سند در انتظار است) به عنوان پیش‌نیاز ساخت NUT به همراه این بخش از پشتیبانی است. برای جزئیات بیشتر (از جمله نحوه ساخت کتابخانه سفارشی و ساخت NUT با آن) لطفاً به NUT PR #2063 مراجعه کنید.


نکته

طبق نسخه کنونی منتشرشده، این درایور از خواندن اطلاعات از UPS پشتیبانی می‌کند. انتظار می‌رود پیاده‌سازی پشتیبانی از نوشتن (تنظیم متغیرهای قابل تغییر یا ارسال دستورات) در نسخه‌های بعدی ارائه شود. این موضوع می‌تواند به‌ویژه بر روتین‌های خاموش شدن میزبان تأثیر بگذارد (نبود قابلیت دستور فعال به UPS برای خاموش شدن یا چرخه مجدد توان در پایان کار). به عنوان یک راهکار موقت، در صورت نیاز می‌توانید apctest (از پروژه "apcupsd") را همراه با "Test to kill power" در فرآیند مراحل پایانی خاموش‌سازی سیستم ادغام کنید.

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

port = string

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

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

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

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

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

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

مثال‌ها:

•-x vendor="Foo.Corporation.*"
•-x vendorid="051d*" (APC)
•-x product=";.*(Smart|Back)-?UPS.*"

bus = regex

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

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


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

device = regex

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

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


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

busport = regex

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

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


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

allow_duplicates

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

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

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


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

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

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

usb_set_altinterface = bAlternateSetting

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

usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out

اجبار به استفاده از شماره‌های خاص رابط، نقطه پایانی (endpoint)، نمایه توصیف‌گر (descriptor index) و غیره، به جای مقدار پیش‌فرض 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) تنظیم و "export" شود)، با یک مقدار عددی مانند 4 ("تمام پیام‌ها صادر می‌شوند").

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

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

porttype=value

تنظیم نوع پورت استفاده‌شده. مقادیر موجود عبارتند از serial برای اتصالات مبتنی بر RS232/485، tcp برای اتصالات TCP/IP و usb برای اتصالات USB.

port=value

بسته به نوع پورت می‌توانید یک پورت را در اینجا انتخاب کنید. برای usb فقط auto پشتیبانی می‌شود، برای serial می‌توانید مسیر یک دستگاه مانند /dev/ttyS0 را مشخص کنید و برای tcp می‌توانید یک آدرس IP یا نام میزبان را همراه با پورت اختیاری مانند example.com:502 مشخص کنید.

baudrate=num

تنظیم سرعت اتصال سریال. مقدار پیش‌فرض baudrate برابر با 9600 است.

parity=value

تنظیم پاریتی (توازن) اتصال سریال. مقادیر موجود عبارتند از N برای هیچ (none)، E برای زوج (even) و O برای فرد (odd). مقدار پیش‌فرض parity برابر با N (none) است.

databits=num

تنظیم بیت‌های داده اتصال سریال. مقدار پیش‌فرض databits برابر با 8 است.

stopbits=num

تنظیم بیت‌های توقف اتصال سریال. مقدار پیش‌فرض stopbits برابر با 1 است.

slaveid=num

تنظیم شناسه slave مادباس. مقدار پیش‌فرض slave id برابر با 1 است.

response_timeout_ms=num

تنظیم مهلت زمانی پاسخ مادباس. مهلت زمانی پیش‌فرض توسط libmodbus تعیین می‌شود. در اتصالات TCP با تاخیر بالا، تنظیم یک مهلت زمانی بالاتر می‌تواند سودمند باشد.

این درایور برای ارتباط با پروتکل مادباس به‌طور مشخص از طریق USB (سریال و TCP بخشی از پایه‌کد مشترک کتابخانه هستند)، به قابلیت‌های پیشرفته libmodbus متکی است. در زمان نگارش این متن، پروژه مشترک کتابخانه صرفاً در انتظار ادغام pull request دارای این قابلیت است.

در حال حاضر، اگر توزیع سیستم‌عامل شما مجموعه قابلیت‌های مورد نیاز را ارائه نمی‌دهد، ممکن است لازم باشد libmodbus اختصاصی خود را بسازید و متعاقباً NUT را در مقابل این کتابخانه مجدداً بسازید، همان‌طور که در ویکی گیت‌هاب NUT در نشانی https://github.com/networkupstools/nut/wiki/APC-UPS-with-Modbus-protocol با جزئیات آمده است.

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

cd ~/
git clone -b rtu_usb https://github.com/networkupstools/libmodbus
cd libmodbus
./autogen.sh
./configure --with-libusb --prefix=/path/to/prefix
make install

نکته
•اگر می‌خواهید این نگارش از فایل‌های کتابخانه را در یک مسیر سیستمی (مانند --prefix=/usr/local/ups برای مطابقت با پیش‌فرض‌های NUT — این کار نیازمند ارتقای دسترسی از طریق sudo است) و نه در دایرکتوری خانگی خود یا مکانی مانند /tmp قرار دهید، ممکن است به ‘make && sudo make install` نیاز داشته باشید.
•در مقابل، ممکن است بخواهید از دستور ./configure --with-libusb --enable-static --disable-shared --prefix=/path/to/prefix استفاده کرده و تنها یک فایل ایستای libmodbus.a بسازید و نصب کنید (می‌تواند به‌خوبی در /tmp یا مکانی با طول عمر کوتاه نصب شود)، تا منطق سفارشی Modbus+USB مستقیماً درون باینری اجرایی apc_modbus ساخته شود و هیچ‌گونه تداخل احتمالی زمان اجرا با یک فایل کتابخانه پویا در جای دیگری از سیستم پیش نیاید.
cd ~/
git clone https://github.com/networkupstools/nut
cd nut
./autogen.sh
./configure --with-drivers=apc_modbus --with-usb --with-modbus \
   --with-modbus-includes=-I/path/to/prefix/include/modbus \
   --with-modbus-libs="-L/path/to/prefix/lib -lmodbus"
make

نکته
•سایر گزینه‌های configure در NUT ممکن است برای رفتار مناسب مورد نیاز باشد، مانند --prefix, --with-confdir, --with-user و --with-group تا با بسته توزیع یا نصب قبلی NUT شما مطابقت داشته باشد.

دستور ./configure --enable-inplace-runtime می‌تواند شروع خوبی برای به ارث بردن پیکربندی ساخت از استقرار موجود NUT باشد، همان‌طور که با جزئیات بیشتر در نشانی https://github.com/networkupstools/nut/wiki/Building-NUT-for-in%E2%80%90place-upgrades-or-non%E2%80%90disruptive-tests توضیح داده شده است.

یک کارت مدیریت شبکه (NMC) در UPS ممکن است یک آدرس IP ثابت/ایستا یا یک آدرس پویا (مثلاً از طریق DHCP) در شبکه شما داشته باشد. به همین دلیل، ممکن است بخواهید یا ناچار باشید از یک سرویس نام‌گذاری پویا برای دسترسی به UPS استفاده کنید. توجه داشته باشید که این موضوع می‌تواند به‌ویژه در هنگام قطعی‌های گسترده برق و خاموش‌سازی سیستم‌ها مشکل‌ساز شود، چرا که ممکن است سرور DHCP/DNS شما پیش از نیاز درایور به تحلیل نام مربوطه از دسترس خارج شده باشد (به‌ویژه در طول هوک‌های مراحل پایانی خاموش‌سازی، زمانی که یک نمونه جدید از برنامه درایور ممکن است صرفاً برای فرمان خاموش شدن یا چرخه مجدد توان به UPS آغاز به کار کند).

شایسته است اطمینان حاصل کنید کلاینت سرویس نام سیستم‌عامل شما می‌تواند نام UPS را برای مدت کافی کش کند، یا از آدرس‌دهی IP ثابت استفاده نمایید (همچنین برای اطمینان بیشتر، افزودن یک مدخل در /etc/hosts تا در صورت نیاز به پیکربندی مجدد فقط یک نقطه برای ویرایش وجود داشته باشد).

•Axel Gembe <axel@gembe.net>

nutupsdrv(8), ups.conf(5)

صفحه اصلی NUT (Network UPS Tools): https://www.networkupstools.org/historic/v2.8.5

06/21/2026 Network UPS Tools 2.8.5