'\" t
.\"     Title: riello_usb
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 06/21/2026
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.5
.\"  Language: Persian
.\"
.TH "RIELLO_USB" "8" "06/21/2026" "Network UPS Tools 2\&.8\&.5" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
riello_usb \- درایور تجهیزات یوپی‌اس با پروتکل Riello از طریق USB
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBriello_usb\fR \-h
.sp
\fBriello_usb\fR \-a \fIUPS_NAME\fR [\fIOPTIONS\fR]
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
.sp
این صفحه راهنما فقط ویژگی‌های خاص سخت‌افزاری درایور riello_usb را مستند می‌کند\&. برای اطلاعات بیشتر درباره درایور اصلی، به \fBnutupsdrv\fR(8) مراجعه کنید\&.
.sp .5v
.RE
.SH "سخت‌افزارهای پشتیبانی‌شده (SUPPORTED HARDWARE)"
.sp
درایور riello_usb از تمام یوپی‌اس‌های جدید Riello دارای درگاه USB پشتیبانی می‌کند\&.
.sp
محصولات قدیمی‌تر UPS شرکت Riello پشتیبانی نمی‌شوند\&.
.SH "آرگومان‌های اضافی (EXTRA ARGUMENTS)"
.PP
\fBport =\fR \fIstring\fR
.RS 4
گزینه‌ای الزامی برای تمامی درایورهای NUT\&. مقداری مانند
\fIvalue\fR
باید تعیین شود، معمولاً
\fBauto\fR
برای درایورهایی که اتصالات USB را مدیریت می‌کنند\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
این مقدار می‌تواند یک مسیر در سیستم‌فایل دستگاه مانند
/dev/usb/hiddev0
باشد، اما استفاده فعلی از API مربوط به libusb مانع از شناسایی و تطبیق از طریق چنین شناسه‌هایی می‌شود\&. همچنین ممکن است ذاتاً غیرقابل‌اعتماد باشند (وابسته به اتصال مجدد کابل و ترتیب شماره‌گذاری دستگاه‌ها)\&. در حال حاضر مقدار واقعی
\fIvalue\fR
نادیده گرفته می‌شود، اما از نظر ساختاری وجود مقداری برای پیکربندی
\fIport\fR
همچنان الزامی است\&.
.sp .5v
.RE
.RE
.sp
امکان کنترل چندین دستگاه UPS به‌طور هم‌زمان از طریق اجرای چندین نمونه از این درایور وجود دارد، به شرطی که بتوان آن‌ها را با تنظیم ترکیبی از گزینه‌های \fBvendor\fR، \fBproduct\fR، \fBvendorid\fR، \fBproductid\fR، \fBserial\fR، \fBbus\fR یا \fBdevice\fR که در ادامه توضیح داده شده‌اند، به‌طور یکتا متمایز کرد\&. برای دستگاه‌ها یا سیستم‌عامل‌هایی که اطلاعات کافی ارائه نمی‌دهند، گزینه \fBallow_duplicates\fR می‌تواند کاربردی باشد (محدود و پرخطر!)\&.
.PP
\fBvendorid =\fR \fIregex\fR, \fBproductid =\fR \fIregex\fR, \fBvendor =\fR \fIregex\fR, \fBproduct =\fR \fIregex\fR, \fBserial =\fR \fIregex\fR
.RS 4
انتخاب یک UPS مشخص، در صورتی که بیش از یک دستگاه از طریق USB متصل باشد\&. هر گزینه یک عبارت منظم گسترده را مشخص می‌کند (برای اطلاعات بیشتر در مورد عبارات منظم به
\fBregex\fR(7)
مراجعه کنید)، که باید با مقادیر رشته‌ای کامل مربوط به
vendor/product/serial
دستگاه UPS (بدون احتساب فاصله‌های سفید پیرامون) یا کل کد هگزادسیمال ۴ رقمی برای
vendorid
و
productid
مطابقت داشته باشد\&.
.sp
برای یافتن رشته‌های مناسب جهت تطبیق، اجرای
\fBlsusb\fR(8)
یا اجرای این درایور NUT با آرگومان خط فرمان
\-DD
را امتحان کنید\&.
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x vendor="Foo\&.Corporation\&.*"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x vendorid="051d*"
(APC)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x product="\&.*(Smart|Back)\-?UPS\&.*"
.RE
.RE
.PP
\fBbus =\fR \fIregex\fR
.RS 4
اختیاری، توصیه نمی‌شود\&.
.sp
انتخاب یک UPS روی یک گذرگاه USB مشخص یا گروهی از گذرگاه‌ها\&. آرگومان یک عبارت منظم است که باید با نام گذرگاهی که UPS به آن متصل است مطابقت داشته باشد (مثلاً
bus="002"
یا
bus="00[2\-3]")
همان‌طور که در لینوکس در مسیر
/sys/bus/usb/devices
یا در خروجی
\fBlsusb\fR(8)
دیده می‌شود؛ شامل صفرهای ابتدایی\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
سیستم‌عامل تضمین نمی‌کند که شماره‌های گذرگاه در طول راه‌اندازی‌های مجدد، بارگذاری مجدد درایورهای هسته یا اتصال مجدد دستگاه (مثلاً تغییر تعداد دستگاه‌های متصل به هاب‌های USB) پایدار باقی بمانند\&.
.sp .5v
.RE
.RE
.PP
\fBdevice =\fR \fIregex\fR
.RS 4
اختیاری، توصیه نمی‌شود\&.
.sp
انتخاب یک UPS روی یک دستگاه USB مشخص یا گروهی از دستگاه‌ها\&. آرگومان یک عبارت منظم است که باید با نام دستگاهی که UPS به آن متصل است مطابقت داشته باشد (مثلاً
device="001"
یا
device="00[1\-2]")
همان‌طور که در لینوکس در مسیر
/sys/bus/usb/devices
یا در خروجی
\fBlsusb\fR(8)
دیده می‌شود؛ شامل صفرهای ابتدایی\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
سیستم‌عامل تضمین نمی‌کند که شماره‌های دستگاه در طول راه‌اندازی‌های مجدد یا اتصال مجدد دستگاه پایدار باقی بمانند\&.
.sp .5v
.RE
.RE
.PP
\fBbusport =\fR \fIregex\fR
.RS 4
اختیاری، توصیه نمی‌شود\&.
.sp
در صورت پشتیبانی توسط سخت‌افزار، سیستم‌عامل و libusb در محیط پیاده‌سازی‌شده خاص، این گزینه باید اجازه دهد به جای مقادیر شمارشی منطقی
device
شماره درگاه‌های فیزیکی روی یک هاب USB مشخص شود، و در نتیجه \(em این مورد باید در طول راه‌اندازی‌های مجدد یا اتصال‌های مجدد نوسان کمتری داشته باشد\&. برای مثال، این مقدار ممکن است در خروجی توپولوژی USB دستور
lsusb \-tv
روی سیستم‌هایی که این ابزار را دارند، مشاهده شود\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
این گزینه در عمل توسط برخی از بیلد‌های NUT پشتیبانی نمی‌شود (در این حالت باید همراه با یک هشدار نادیده گرفته شود)، و همچنین توسط تمام سیستم‌هایی که NUT می‌تواند روی آن‌ها اجرا شود نیز پشتیبانی نمی‌گردد\&.
.sp .5v
.RE
.RE
.PP
\fBallow_duplicates\fR
.RS 4
اختیاری، توصیه نمی‌شود\&.
.sp
اگر چندین دستگاه UPS دارید که ممکن است توسط گزینه‌های بالا به‌طور یکتا شناسایی نشوند (مثلاً فقط
\fIVID:PID\fR
در آنجا قابل کشف باشد)، این فلگ به هر نمونه درایور که در آن تنظیم شده اجازه می‌دهد اولین تطابق را در صورت موجود بودن انتخاب کند، یا برای بررسی مورد دیگر ادامه دهد\&.
.sp
به‌طور معمول، راه‌اندازی اولیه درایور در این مرحله با اعلام خطای "Resource busy" یا خطایی مشابه متوقف می‌شود، با این فرض که دستگاهی که به‌درستی تطبیق داده شده یکتا است \(em و فرایند دیگری در حال حاضر آن را مدیریت می‌کند\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBهشدار\fR
.ps -1
.br
این ویژگی ذاتاً غیرقطعی (non\-deterministic) است! انتساب نام نمونه درایور به دستگاه واقعی ممکن است بین دفعات اجرا متفاوت باشد!
.sp
اگر فقط برایتان مهم است که بدانید
\fBحداقل\fR
یکی از یوپی‌اس‌های بی‌نام شما آنلاین است، این گزینه می‌تواند کمک کند\&.
.sp
اما اگر واقعاً نیاز دارید بدانید
\fBکدام\fR
دستگاه است، کمکی نخواهد کرد!
.sp .5v
.RE
.RE
.PP
\fBusb_set_altinterface =\fR \fIbAlternateSetting\fR
.RS 4
فراخوانی افزونه و اجباری
usb_set_altinterface()،
به‌ویژه در صورت نیاز برای دستگاه‌هایی که چندین نقش USB مختلف ایفا می‌کنند و در آن‌ها UPS با شماره رابط
0
(پیش‌فرض) نشان داده نمی‌شود\&.
.RE
.PP
\fBusb_config_index\fR, \fBusb_hid_rep_index\fR, \fBusb_hid_desc_index\fR, \fBusb_hid_ep_in\fR, \fBusb_hid_ep_out\fR
.RS 4
اجبار به استفاده از شماره‌های خاص رابط، نقطه انتهایی (endpoint)، شاخص توصیف‌کننده (descriptor index) و غیره، به جای مقدار پیش‌فرض
\fI0\fR
(در برخی درایورها برای دستگاه‌های خاصی که از شماره‌های غیرصفر استفاده می‌کنند، مقادیر دیگری به‌ندرت دیده می‌شود)\&. این مقدار به‌صورت یک عدد هگزادسیمال مشخص می‌شود\&.
.sp
به عنوان یک قاعده کلی برای تشخیص
usb_hid_desc_index
می‌توانید مقادیر بزرگ‌تر
wDescriptorLength
(تقریباً بیش از ۶۰۰ بایت) را در گزارش‌های
lsusb
یا ابزارهای مشابه مشاهده کنید\&.
.RE
.PP
\fBLIBUSB_DEBUG =\fR \fIINTEGER\fR
.RS 4
عیب‌یابی زمان اجرای درایورهای NUT با قابلیت USB نه‌تنها شامل افزایش سطح گزارش‌دهی اشکال‌زدایی معمول NUT است (مثلاً با استفاده از تنظیم
DEBUG_MIN
در
\fBups.conf\fR(5)
یا دستورات پروتکل برای تغییر مقدار
driver\&.debug)،
بلکه می‌تواند از اشکال‌زدایی اختصاصی LibUSB نیز بهره‌مند شود\&.
.sp
برای مورد دوم، می‌توانید گزینه درایور
LIBUSB_DEBUG
را تنظیم کنید؛ به عنوان روش جایگزین سنتی نیز می‌توانید پیش از شروع برنامه درایور NUT، متغیر محیطی
LIBUSB_DEBUG
را صادر (export) کنید (می‌تواند در اسکریپت راه‌اندازی اولیه درایور یا متد سرویس، شاید از طریق
\fBnut.conf\fR(5)
تنظیم و "export" شود)، با یک مقدار عددی مانند
4
("All messages are emitted" یا «همه پیام‌ها ارسال شوند»)\&.
.sp
برای جزئیات بیشتر، از جمله مقادیر پشتیبانی‌شده کنونی برای نسخه کتابخانه شما، برای مثال ببینید:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
https://libusb\&.sourceforge\&.io/api\-1\&.0
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
https://libusb\&.sourceforge\&.io/api\-1\&.0/group__libusb__lib\&.html
.RE
.RE
.sp
بسته به سازنده و مدل UPS خود، ممکن است لازم باشد برخی تنظیمات را تغییر دهید (به \fBups.conf\fR(5) مراجعه کنید):
.PP
\fBlocalcalculation\fR
.RS 4
در صورت فعال بودن، درایور مقادیر
battery\&.runtime
و
battery\&.charge
را به‌صورت "محلی" (داخلی) درون درایور محاسبه می‌کند\&. این ویژگی برای برخی از مدل‌های Riello (سری‌های iPlug و iDialog) کاربرد دارد که مقادیر نادرستی را در خوانش‌های سخت‌افزاری ارائه می‌دهند یا اصلاً هیچ مقداری ارائه نمی‌کنند\&. این "محاسبه محلی" بر اساس ظرفیت اسمی باتری، ولتاژ اسمی باتری، شارژ واقعی باتری و حداکثر بار و بار واقعی UPS انجام می‌شود\&.
.sp
همچنین ممکن است بخواهید
\fIdefault\&.battery\&.voltage\&.low\fR
و
\fIdefault\&.battery\&.voltage\&.high\fR
را در صورتی که محدوده پیش‌فرض داخلی (از 10\&.7V تا 12\&.9V) با سخت‌افزار شما مطابقت ندارد پیکربندی کنید، یا در صورتی که دستگاه شما ولتاژ اسمی را نیز ارائه نمی‌دهد، مقدار
\fIdefault\&.battery\&.voltage\&.nominal\fR
(مثلاً
\fI24\fR)
را امتحان نمایید\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBنکته\fR
.ps -1
.br
نمودار شارژ باتری‌های سربی\-اسیدی (PbAc) خطی نیست، بنابراین مقدار تخمینی شارژ ممکن است کاملاً دقیق نباشد\&. با این حال برای تعیین وضعیت واقعی باتری و برآورد تقریبی مدت زمانی که همچنان می‌تواند سیستم را تغذیه کند به اندازه کافی مناسب خواهد بود\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBهشدار\fR
.ps -1
.br
این کلیدواژه ممکن است در نسخه‌های آینده درایور به نفع
runtimecal
و سایر تنظیمات مورد نیاز آن (همان‌طور که در درایورهای
\fBnutdrv_qx\fR(8)،
\fBblazer_ser\fR(8)
و
\fBblazer_usb\fR(8)
دیده می‌شود) منسوخ (deprecated) شود\&.
.sp .5v
.RE
.RE
.SH "نویسنده (AUTHOR)"
.sp
Massimo Zampieri
.SH "همچنین ببینید (SEE ALSO)"
.SS "درایورهای مرتبط (Related drivers)"
.sp
\fBriello_ser\fR(8)
.SS "درایور اصلی (The core driver)"
.sp
\fBnutupsdrv\fR(8)
.SS "منابع اینترنتی (Internet resources)"
.sp
صفحه اصلی NUT (Network UPS Tools): https://www\&.networkupstools\&.org/historic/v2\&.8\&.5