AMPCTL(1)                      Hamlib Utilities                      AMPCTL(1)

نام (NAME)
       ampctl - کنترل تقویت‌کننده‌های رادیویی

خلاصه دستور (SYNOPSIS)
       ampctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
              [-v[-Z]] [command|-]

توضیحات (DESCRIPTION)
       کنترل تقویت‌کننده‌های رادیویی (آمپلی‌فایرها).  برنامه ampctl دستورات را از
       خط فرمان و همچنین در صورت عدم ارائه در خط فرمان، در حالت تعاملی دریافت
       می‌کند.

       توجه داشته باشید که Hamlib نرم‌افزاری در سطح بتا (BETA) است. در حالی که
       بسیاری از کتابخانه‌های بک‌اند فاقد پشتیبانی کامل از تقویت‌کننده هستند،
       توابع پایه معمولاً به خوبی پشتیبانی می‌شوند.

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

گزینه‌ها (OPTIONS)
       این برنامه از سینتکس معمول خط فرمان گنو پیروی می‌کند. گزینه‌های کوتاهی که
       آرگومان می‌پذیرند می‌توانند مقدار را بلافاصله پس از خود داشته باشند یا با
       یک فاصله جدا شوند. گزینه‌های بلندی که با دو خط‌تیره (‘-’) آغاز می‌شوند، به
       علامت ‘=’ میان گزینه و آرگومان نیاز دارند.

       خلاصه‌ای از گزینه‌های پشتیبانی‌شده در ادامه آمده است:

       -m, --model=id
              انتخاب شماره مدل تقویت‌کننده.

              فهرست مدل‌ها را ببینید (اجرای “ampctl -l”).

              توجه: برنامه ampctl (یا نرم‌افزارهای شخص ثالث با استفاده از C
              API) از مدل شماره ۲ برای NET ampctl (جهت ارتباط با ampctld)
              استفاده خواهند کرد.

       -r, --amp-file=device
              استفاده از device به‌عنوان نام فایل درگاه متصل به تقویت‌کننده.

              اغلب یک درگاه سریال است، اما می‌تواند مبدل USB به سریال باشد.
              به‌طور معمول /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0 و غیره در
              لینوکس، و COM1, COM2 و غیره در ویندوز. توزیع‌های BSD و Mac OS/X
              نام‌گذاری‌های اختصاصی خود را دارند. به مستندات سیستم خود مراجعه
              فرمایید.

       -s, --serial-speed=baud
              تنظیم سرعت سریال بر حسب baud (نرخ باود).

              به‌طور پیش‌فرض از حداکثر سرعت پورت سریال بر اساس قابلیت‌های بک‌اند
              تقویت‌کننده (تنظیم‌شده با -m در بالا) استفاده می‌کند.

       -t, --send-cmd-term=char
              تغییر نویسه پایانه‌ساز (termination char) برای پروتکل متنی در
              هنگام استفاده از دستور send_cmd.

              مقدار پیش‌فرض CR اسکی (‘0x0D’) است. نویسه‌های غیرقابل چاپ اسکی را
              می‌توان به‌صورت عدد اسکی در مبنای ۱۶ با پیشوند “0x” مشخص کرد.
              می‌توانید یک رشته خالی برای عدم استفاده از نویسه پایانه‌ساز ارسال
              کنید. ارسال رشته “-1” به ampctl می‌گوید که به پروتکل دودویی
              (باینری) تغییر وضعیت دهد.

              برای مثال، جهت تعیین پایانه‌ساز برای دستورات متنی به سبک Kenwood،
              مقدار “-t ';'” را به ampctl ارسال کنید. بخش مثال‌ها در ادامه را
              ببینید.

       -L, --show-conf
              فهرست کردن تمام پارامترهای پیکربندی برای تقویت‌کننده تعریف‌شده با
              گزینه -m در بالا.

       -C, --set-conf=parm=val[,parm=val]
              تنظیم پارامتر(های) پیکربندی تقویت‌کننده، مانند stop_bits=2.

              از گزینه -L در بالا برای دریافت فهرستی از پارامترهای پیکربندی
              برای یک شماره مدل خاص استفاده کنید.

       -u, --dump-caps
              استخراج قابلیت‌های تقویت‌کننده تعریف‌شده با -m در بالا و سپس خروج.

       -l, --list
              فهرست کردن تمام شماره مدل‌های تقویت‌کننده تعریف‌شده در Hamlib و سپس
              خروج.

              فهرست بر اساس شماره مدل مرتب شده است.

              توجه: در لینوکس می‌توان فهرست را با استفاده از
              Shift-PageUp/Shift-PageDown یا نوار پیمایش ترمینال مجازی در X یا
              پنجره cmd در ویندوز به بالا و پایین پیمایش کرد. خروجی را می‌توان
              به more(1) یا less(1) هدایت نمود (پایپ کرد)، مانند “ampctl -l |
              more”.

       -i, --read-history
              خواندن تاریخچه دستورات و آرگومان‌های ذخیره‌شده قبلی از یک فایل
              (پیش‌فرض $HOME/.ampctl_history) برای نشست جاری.

              در صورتی در دسترس است که ampctl با پشتیبانی از Readline کامپایل
              شده باشد (بخش ریدلاین را در ادامه ببینید).

              توجه: برای خواندن فایل تاریخچه ذخیره‌شده در یک دایرکتوری دیگر،
              متغیر محیطی AMPCTL_HIST_DIR را تنظیم کنید؛ برای مثال
              “AMPCTL_HIST_DIR=~/tmp ampctl -i”. در صورت عدم تنظیم
              AMPCTL_HIST_DIR، مقدار متغیر HOME استفاده می‌شود.

       -I, --save-history
              نوشتن تاریخچه دستورات و آرگومان‌های نشست جاری (و نشست(های) قبلی،
              در صورتی که گزینه -i داده شده باشد) در یک فایل (پیش‌فرض
              $HOME/.ampctl_history) در پایان نشست جاری.

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

              توجه: برای نوشتن فایل تاریخچه در دایرکتوری دیگر، متغیر محیطی
              AMPCTL_HIST_DIR را تنظیم کنید، مانند “AMPCTL_HIST_DIR=~/tmp
              ampctl -I”. در صورت عدم تنظیم AMPCTL_HIST_DIR، مقدار HOME
              استفاده می‌شود.

       -v, --verbose
              تنظیم حالت پرگویی (verbose) به‌صورت تجمعی (بخش عیب‌یابی در ادامه
              را ببینید).

       -Z, --debug-time-stamps
              فعال کردن برچسب زمانی برای پیام‌های اشکال‌زدایی.

              تنها در ترکیب با گزینه -v استفاده شود، زیرا به‌تنهایی خروجی تولید
              نمی‌کند.

       -h, --help
              نمایش خلاصه‌ای از این گزینه‌ها و سپس خروج.

       -V, --version
              نمایش نسخه ampctl و سپس خروج.

       -      توقف پردازش گزینه‌ها و خواندن دستورات از ورودی استاندارد.

              بخش ورودی استاندارد در ادامه را ببینید.

       توجه: برخی از گزینه‌ها ممکن است توسط بک‌اند خاصی پیاده‌سازی نشده باشند و
       خطایی بازگردانند. این موضوع بیشتر در مورد گزینه‌های --set-conf و
       --show-conf رخ می‌دهد.

       لطفاً توجه داشته باشید که بک‌اند تقویت‌کننده مورد نظر یا خود تقویت‌کننده
       ممکن است از برخی دستورات پشتیبانی نکنند. در این صورت، عملیات با یک کد
       خطای Hamlib با شکست مواجه خواهد شد.

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

           F 14250000

       از آنجا که بیشتر عملیات Hamlib دارای یک متد set و یک متد get هستند،
       اغلب از یک حرف بزرگ انگلیسی برای متد set استفاده می‌شود، در حالی که حرف
       کوچک متناظر آن به متد get اشاره دارد. هر عملیات یک نام طولانی نیز دارد؛
       در حالت تعاملی، با افزودن یک بک‌اسلش ‘\’ در ابتدا، می‌توان نام بلند دستور
       را وارد کرد.

       مثال: برای مشاهده قابلیت‌های پشتیبانی‌شده توسط تقویت‌کننده و بک‌اند، دستور
       “\dump_caps” را وارد کنید.

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

       یک مثال ساده با استفاده از دستورات ذخیره‌شده در یک فایل (متن تایپ‌شده
       به‌صورت توپر نمایش داده شده است):

           $ cat <<.EOF. >cmds.txt
           > # File of commands
           > F 14250000
           > f
           > l PWRINPUT
           > l PWRFORWARD
           > l SWR
           > \dump_caps
           > .EOF.
           $ ampctl -m1 - <cmds.txt

           Amplifier command: # File of commands

           Amplifier command: F 14250000

           Amplifier command: f
           Frequency(Hz): 14250000

           Amplifier command: l PWRINPUT
           Level Value: 0

           Amplifier command: l PWRFORWARD
           Level Value: 1499

           Amplifier command: l SWR
           Level Value: 1.000000

           Amplifier command: \dump_caps
           Caps dump for model:    1
           Model name:             Dummy
           Mfg name:               Hamlib
           Backend version:        0.1
           Backend copyright:      LGPL
           Backend status:         Alpha
           Amp type:               Other
           Port type:              None
           Write delay:            0mS, timeout 0mS, 0 retries
           Post Write delay:       0mS
           Has priv data:          N
           Get level: SWR NH PF PWRINPUT PWRFORWARD PWRREFLECTED PWRPEAK FAULT
           Has Init:               Y
           Has Cleanup:            Y
           Has Open:               Y
           Has Close:              Y
           Can set Conf:           N
           Can get Conf:           N
           Can Reset:              Y
           Can get Info:           Y

           Overall backend warnings: 0

           Amplifier command:

           $

   دستورات ampctl
       خلاصه‌ای از دستورات در ادامه آمده است (در مورد دستورات set، رشته مورب
       داخل گیومه با مقدار شرح‌داده‌شده جایگزین می‌شود. در مورد دستورات get، رشته
       مورب داخل گیومه نام کلید مقدار بازگردانده‌شده است):

       Q|q, exit ampctl
              خروج از ampctl در حالت تعاملی.

              هنگامی که ampctl تقویت‌کننده را مستقیماً کنترل می‌کند، بک‌اند
              تقویت‌کننده و درگاه بسته خواهند شد. هنگامی که ampctl به ampctld
              متصل است (مدل شماره ۲ تقویت‌کننده)، اتصال TCP/IP به ampctld بسته
              می‌شود و ampctld همچنان در حال اجرا و آماده برای اتصال شبکه
              TCP/IP دیگر باقی می‌ماند.

       F, set_freq 'Frequency'
              تنظیم 'Frequency' (فرکانس)، بر حسب هرتز (Hz).

              فرکانس می‌تواند یک مقدار اعشاری یا عدد صحیح باشد.

       f, get_freq
              دریافت 'Frequency' (فرکانس)، بر حسب هرتز.

              یک مقدار عدد صحیح بازمی‌گرداند.

       l, get_level 'Level'
              دریافت 'Level Value' (مقدار سطح).

              مقدار سطح را به‌صورت عدد اعشاری یا صحیح برای نشانه سطح ارائه‌شده
              برمی‌گرداند.

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

       w, send_cmd 'Cmd'
              ارسال یک رشته دستور خام (raw) به تقویت‌کننده.

              این دستور برای آزمایش و عیب‌یابی دستورات و پاسخ‌های تقویت‌کننده در
              حین توسعه بک‌اند بسیار مفید است.

              برای پروتکل‌های دودویی مقادیر را به‌صورت \0xAA\0xBB وارد کنید.
              انتظار یک 'Reply' (پاسخ) از سوی تقویت‌کننده را داشته باشید که
              بسته به پروتکل تقویت‌کننده احتمالاً یک بلوک دودویی یا یک رشته اسکی
              خواهد بود (به مستندات کنترل رایانه‌ای تقویت‌کننده خود مراجعه
              فرمایید).

              نویسه پایانه‌ساز دستور که توسط گزینه send-cmd-term در بالا تنظیم
              شده است، رشته هر دستور ارسال‌شده به تقویت‌کننده را خاتمه می‌دهد.
              این نویسه نباید بخشی از رشته ورودی باشد.

       dump_state
              بازگرداندن اطلاعات وضعیت خاص درباره بک‌اند تقویت‌کننده.

       1, dump_caps
              یک دستور واقعی کنترل از راه دور تقویت‌کننده نیست؛ صرفاً قابلیت‌ها،
              یعنی آنچه را که بک‌اند درباره این مدل می‌داند و کارهایی را که
              می‌تواند انجام دهد استخراج و نمایش می‌دهد.

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

              توجه: این دستور خطوط خروجی زیادی تولید می‌کند، بنابراین هنگام
              استفاده از آرایه‌ای با طول ثابت بسیار دقت کنید! برای مثال، اجرای
              این دستور بر روی بک‌اند مجازی (Dummy) خطوط متعددی از متن خروجی را
              تولید می‌کند.

       _, get_info
              بازگرداندن اطلاعات از بک‌اند تقویت‌کننده.

       R, reset 'Reset'
              انجام 'Reset' (بازنشانی) تقویت‌کننده.

              مقدار Reset یک عدد صحیح است: ‘0’ = هیچ‌کدام، ‘1’ = بازنشانی
              حافظه، ‘2’ = بازنشانی خطا، ‘3’ = بازنشانی تقویت‌کننده.

       set_powerstat 'Power Status'
              تنظیم 'Power Status' (وضعیت توان).

              وضعیت توان یک مقدار عدد صحیح است: ‘0’ = خاموش، ‘1’ = روشن، ‘2’ =
              آماده‌به‌کار (ورود به حالت Standby)، ‘4’ = عملیاتی (خروج از
              Standby و ورود به Operate).

       get_powerstat
              دریافت 'Power Status' همانند set_powerstat در بالا.

       Y, set_ant 'Antenna' 'Option'
              تنظیم 'Antenna' (آنتن) و 'Option' (گزینه).

              شماره آنتن شماره‌گذاری بر پایه ۱ است (‘1’، ‘2’، ‘3’، ...).

                  1 = A/1
                  2 = B/2
                  3 = C/3

ریدلاین (READLINE)
       اگر فایل‌های توسعه کتابخانه Readline در زمان پیکربندی یافت شوند، ampctl
       به‌طور مشروط با پشتیبانی از Readline برای ورود دستورات و آرگومان‌ها
       کامپایل خواهد شد. کلیدهای میانبر دستورات Readline در حالت پیش‌فرض خود
       هستند، همان‌طور که در راهنمای Readline
       <https://tiswww.cwru.edu/php/chet/readline/rluserman.html> توصیف شده
       است.  ampctl نام “ampctl” را تعریف می‌کند که می‌تواند در ساختارهای اولیه
       شرطی در فایل پیکربندی Readline (به‌طور پیش‌فرض $HOME/.inputrc) برای
       کلیدهای میانبر سفارشی و اختصاصی ampctl به کار رود.

       تاریخچه دستورات با پشتیبانی Readline در دسترس است، همان‌طور که در
       راهنمای تاریخچه Readline
       <https://tiswww.case.edu/php/chet/readline/history.html#SEC1> بیان شده
       است. رشته‌های دستور و آرگومان به‌صورت خطوط منفرد ذخیره می‌شوند، حتی زمانی
       که برای ورود تک‌تک آرگومان‌ها اعلان داده شود. دستورات و آرگومان‌ها
       اعتبارسنجی نمی‌شوند و دقیقاً همان‌گونه که تایپ شده‌اند و با فاصله‌ای تکی از
       یکدیگر ذخیره می‌گردند.

       به‌طور معمول تاریخچه نشست ذخیره نمی‌شود، اما استفاده از هر یک از گزینه‌های
       -i/--read-history یا -I/--save-history هنگام اجرای ampctl باعث خواندن
       تاریخچه ذخیره‌شده پیشین و/یا نوشتن تاریخچه نشست فعلی و پیشین (با فرض
       استفاده همزمان از گزینه‌های -i و -I) در زمان بستن ampctl می‌شود. این
       گزینه‌ها متقابلاً انحصاری نیستند و می‌توان هر کدام را جداگانه یا همراه با
       یکدیگر به کار برد. این امر برای ذخیره مجموعه‌ای از دستورات و خواندن بعدی
       آن‌ها بدون بازنویسی تاریخچه تغییریافته مفید است؛ برای مثال برای مجموعه‌ای
       ثابت از دستورات آزمایشی در حالت تعاملی.

       تاریخچه به‌طور پیش‌فرض در فایل $HOME/.ampctl_history ذخیره می‌شود، هرچند
       که می‌توان دایرکتوری مقصد را با تنظیم متغیر محیطی AMPCTL_HIST_DIR تغییر
       داد. زمانی که AMPCTL_HIST_DIR تنظیم نشده باشد، مقدار متغیر محیطی HOME
       به جای آن استفاده می‌شود. در حال حاضر فقط دایرکتوری مقصد قابل تغییر است.

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

       توجه: پشتیبانی از Readline در نسخه‌های باینری ۳۲ بیتی یا ۶۴ بیتی MS
       Windows که توسط پروژه Hamlib ارائه می‌شوند گنجانده نشده است. اجرای
       ampctl روی سیستم‌عامل MS Windows در محیط شل ‘cmd’ تاریخچه دستورات نشست
       را فراهم می‌کند، اما بین نشست‌ها روی دیسک ذخیره نمی‌شود.

عیب‌یابی (DIAGNOSTICS)
       گزینه -v, --verbose امکان می‌دهد سطوح مختلف اطلاعات عیب‌یابی به stderr
       ارسال شود که متناظر است با -v برای BUG, -vv برای ERR, -vvv برای WARN,
       -vvvv برای VERBOSE, یا -vvvvv برای TRACE.

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

وضعیت خروج (EXIT STATUS)
       دستور ampctl با وضعیت‌های زیر پایان می‌یابد:

       0      اگر تمام عملیات‌ها به‌طور عادی تکمیل شده باشند؛

       1      اگر گزینه یا آرگومان نامعتبری در خط فرمان داده شده باشد؛

       2      اگر خطایی از سوی Hamlib بازگردانده شده باشد.

مثال‌ها (EXAMPLES)
       اجرای ampctl برای تقویت‌کننده Elecraft KPA-1500 با استفاده از مبدل USB
       به سریال در لینوکس در حالت تعاملی:

           $ ampctl -m 201 -r /dev/ttyUSB1

       اجرای ampctl برای Elecraft KPA-1500 با استفاده از پورت COM1 در MS
       Windows به همراه تولید خروجی TRACE در stderr:

           > ampctl -m 201 -r COM1 -vvvvv

       اتصال به یک نسخه در حال اجرای ampctld با مدل ۲ تقویت‌کننده (“NET
       ampctl”) روی میزبان محلی (localhost) و تعیین پورت TCP، تنظیم فرکانس و
       حالت:

           $ ampctl -m 2 -r localhost:4531 F 7253500

اشکالات (BUGS)
       گزارش اشکالات به:

              Hamlib Developer mailing list
              <hamlib-developer@lists.sourceforge.net
              >

کپی‌رایت و تکثیر (COPYING)
       این فایل بخشی از Hamlib است، پروژه‌ای برای توسعه کتابخانه‌ای که توابع
       کنترل رادیو، روتاتور و تقویت‌کننده را برای توسعه‌دهندگان نرم‌افزار، عمدتاً
       رادیوآماتورها و علاقه‌مندان به ارتباطات رادیویی، ساده می‌کند.

       Copyright © 2000-2011 Stephane Fillod
       Copyright © 2000-2018 the Hamlib Group (various contributors)
       Copyright © 2010-2020 Nate Bargmann

       این نرم‌افزار آزاد است؛ برای آگاهی از شرایط تکثیر فایل COPYING را
       ببینید. هیچ ضمانتی وجود ندارد؛ حتی برای بازاریابی تجاری یا تناسب برای
       یک هدف مشخص.

همچنین ببینید (SEE ALSO)
       less(1), more(1), ampctld(1), hamlib(7)

شناسنامه (COLOPHON)
       پیوندها به ویکی Hamlib، مخزن Git، بایگانی‌های نسخه‌های عرضه‌شده و
       اسنپ‌شات‌های روزانه از طریق نشانی زیر در دسترس است: hamlib.org
       <http://www.hamlib.org>.

Hamlib                            2020-09-08                         AMPCTL(1)