| AMPCTLD(1) | Hamlib Utilities | AMPCTLD(1) |
نام (NAME)
ampctld - دیمن کنترل تقویتکننده تحت TCP
خلاصه دستور (SYNOPSIS)
ampctld |
[-hlLuV] [-m id] [-r device] [-s baud] [-T IPADDR] [-t number] [-C parm=val] [-v[-Z]] |
توضیحات (DESCRIPTION)
برنامه ampctld یک دیمن کنترل تقویتکننده است که درخواستهای کلاینت را از طریق سوکتهای TCP مدیریت میکند. این قابلیت به چندین برنامه کاربر امکان میدهد یک تقویتکننده را به اشتراک بگذارند (این ویژگی نیازمند توسعه بیشتر است). چندین تقویتکننده را میتوان با استفاده از چندین فرایند ampctld روی درگاههای TCP مختلف کنترل کرد. توجه داشته باشید در صورتی که برخی از کلاینتها از پاسخهای توسعهیافته (extended responses) و/یا حالت vfo استفاده کنند، استفاده از چندین فرایند/درگاه نیز الزامی خواهد بود. بنابراین ممکن است برای هر ترکیب از پاسخ توسعهیافته/حالت vfo به حداکثر ۴ فرایند/درگاه نیاز باشد. نحو دستورها همانند ampctl(1) است. امید میرود که ampctld بهویژه برای نویسندگان کلاینت که از زبانهایی مانند Perl، Python، PHP و غیره استفاده میکنند، مفید واقع شود.
ampctld از طریق یک سوکت TCP با استفاده از دستورهای متنی مشترک با ampctl با کلاینت ارتباط برقرار میکند. پروتکل ساده است؛ دستورها در یک خط به ampctld ارسال میشوند و ampctld در صورت موفقیت، به دستورهای get با مقادیر درخواستی (هر مقدار در یک خط) پاسخ میدهد؛ در غیر این صورت، پاسخی در قالب یک خط حاوی “RPRT x” بازمیگرداند که در آن ‘x’ یک عدد منفی نشاندهنده کد خطا است. دستورهایی که مقداری را برنمیگردانند با خط “RPRT x” پاسخ میدهند که در آن ‘x’ در صورت موفقیت برابر ‘0’ و در غیر این صورت یک عدد منفی نشاندهنده کد خطا است. هر خط با نویسه خط جدید ‘\n’ پایان مییابد. این پروتکل عمدتاً برای استفاده توسط بکاندِ NET ampctl (تقویتکننده مدل ۲) است.
یک Extended Response Protocol مجزا، رفتار فوق را با بازتاب دادن رشته دستور دریافتی به عنوان سرآیند، هر مقدار بازگشتی به عنوان یک جفت key: value، و رشته “RPRT x” به عنوان نشانگر پایان پاسخ که شامل مقدار موفقیت یا شکست Hamlib است، گسترش میدهد. برای جزئیات به بخش PROTOCOL مراجعه کنید. استفاده از این پروتکل را برای کلاینتهایی که مستقیماً از طریق سوکت TCP با ampctld تعامل دارند در نظر داشته باشید.
به یاد داشته باشید که Hamlib نرمافزاری در سطح آزمایشی (BETA) است. اگرچه بسیاری از کتابخانههای بکاند فاقد پشتیبانی کامل از تقویتکننده هستند، اما عملکردهای پایهای معمولاً به خوبی پشتیبانی میشوند.
لطفاً باگها را گزارش کرده و بازخورد خود را به نشانی ایمیل ارائهشده در بخش گزارش باگها (BUGS) در زیر ارسال کنید. از وصلهها و بهبودهای کد ارسالی به همین نشانی استقبال میشود. این برنامه از نحو معمول خط فرمان GNU پیروی میکند. در گزینههای کوتاه که یک آرگومان دریافت میکنند، مقدار میتواند بلافاصله پس از گزینه بیاید یا با یک فاصله از آن جدا شود. گزینههای طولانی که با دو خط تیره (‘-’) آغاز میشوند، به یک ‘=’ میان گزینه و هر آرگومان نیاز دارند.
در اینجا خلاصهای از گزینههای پشتیبانیشده آورده شده است:
- -m, --model=id
- انتخاب شماره مدل تقویتکننده (amplifier).
- فهرست مدلها را ببینید (از “ampctl -l” استفاده کنید).
- نکته: برنامه ampctl (یا نرمافزارهای شخص ثالثی که از C API استفاده میکنند) از مدل تقویتکننده ۲ برای NET ampctl (جهت ارتباط با ampctld) استفاده خواهد کرد.
- -r, --amp-file=device
- استفاده از device بهعنوان نام فایل پورت متصل به تقویتکننده.
- اغلب یک پورت سریال است، اما میتواند یک مبدل USB به سریال نیز باشد. معمولاً /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0 و غیره در لینوکس، و COM1, COM2 و غیره در MS Windows است. توزیعهای BSD و Mac OS/X نامگذاریهای خاص خود را دارند. مستندات سیستم خود را ببینید.
- -s, --serial-speed=baud
- تنظیم سرعت سریال روی نرخ baud.
- بهطور پیشفرض از حداکثر سرعت سریال برگرفته از قابلیتهای باکاند تقویتکننده (تنظیمشده توسط -m در بالا) استفاده میکند.
- -t, --port=number
- استفاده از number بهعنوان پورت شنود TCP.
- مقدار پیشفرض 4531 است.
- نکته: از آنجا که پورت پیشفرض rigctld برابر با 4532 و پورت پیشفرض rotctld برابر با 4533 است، توصیه میشود برای چندین نمونه از ampctld از پورتهای فرد نزولی استفاده شود؛ مانند 4529، 4527، 4525 و غیره.
- -T, --listen-addr=IPADDR
- استفاده از IPADDR بهعنوان آدرس IP شنود.
- مقدار پیشفرض ANY است.
- -L, --show-conf
- فهرست کردن تمام پارامترهای پیکربندی برای تقویتکنندهٔ تعریفشده با -m در بالا.
- -C, --set-conf=parm=val[,parm=val]
- تنظیم پارامتر(های) پیکربندی تقویتکننده، مانند stop_bits=2.
- برای مشاهدهٔ فهرست پارامترهای پیکربندی یک شماره مدل مشخص، از گزینهٔ -L در بالا استفاده کنید.
- -u, --dump-caps
- تخلیه (dump) قابلیتهای تقویتکنندهٔ تعریفشده با -m در بالا و خروج.
- -l, --list
- فهرست کردن تمام شمارههای مدل تقویتکنندهٔ تعریفشده در Hamlib و خروج.
- این فهرست بر اساس شماره مدل مرتب شده است.
- نکته: در لینوکس میتوان با استفاده از Shift-PageUp/Shift-PageDown یا با استفاده از نوارهای پیمایش یک ترمینال مجازی در X یا پنجره cmd در ویندوز، فهرست را به عقب پیمایش کرد. خروجی را میتوان به more(1) یا less(1) نیز هدایت (pipe) کرد؛ مانند “ampctl -l | more”.
- -v, --verbose
- تنظیم حالت پرگو (verbose)، بهصورت تجمعی (بخش خطاها (DIAGNOSTICS) در زیر را ببینید).
- -Z, --debug-time-stamps
- فعال کردن برچسبهای زمانی برای پیامهای اشکالزدایی (debug).
- تنها در ترکیب با گزینهٔ -v استفاده شود، زیرا بهتنهایی خروجی تولید نمیکند.
- -h, --help
- نمایش خلاصهای از این گزینهها و خروج.
- -V, --version
- نمایش نسخهٔ ampctl و خروج.
نکته: برخی از گزینهها ممکن است توسط یک باکاند خاص پیادهسازی نشده باشند و خطایی بازگردانند. این مورد بیشتر برای گزینههای --set-conf و --show-conf رخ میدهد.
لطفاً توجه داشته باشید که باکاند مربوط به تقویتکنندهٔ تحت کنترل، یا خودِ تقویتکننده ممکن است از برخی دستورها پشتیبانی نکنند. در این صورت، عملیات با یک کد خطای Hamlib شکست خواهد خورد. دستورها میتوانند از طریق سوکت TCP به صورت یک تکنویسه، یا به صورت نام بلند دستور بههمراه مقدارهای جداشده با فاصله در یک خط که به ‘\n’ ختم میشود، ارسال شوند. بخش PROTOCOL را ببینید.
از آنجا که بیشتر عملیاتهای Hamlib دارای یک متد set و یک متد get هستند، یک حرف بزرگ انگلیسی برای متدهای set بهکار میرود در حالی که حرف کوچک متناظر با آن به متد get اشاره دارد. هر عملیات همچنین یک نام بلند دارد؛ برای ارسال نام بلند دستور، یک بکاسلش، ‘\’، را به ابتدای آن اضافه کنید.
مثال (Perl): “print $socket "\\dump_caps\n";” برای دیدن کارهایی که بکاند تقویتکننده (amplifier) میتواند انجام دهد (نکته: در Perl و بسیاری از زبانهای دیگر یک ‘\’ باید با یک ‘\’ قبل از خود گریز (escape) داده شود، بنابراین حتی اگر دو نویسه بکاسلش در کد دیده شود، تنها یک نویسه به ampctld ارسال خواهد شد. این ممکن است خطاساز باشد، مراقب باشید!).
نکته: بکاند مربوط به تقویتکنندهای که قرار است کنترل شود، یا خود تقویتکننده، ممکن است از برخی دستورها پشتیبانی نکنند. در این صورت، عملیات با یک پیام خطای Hamlib شکست میخورد.
در ادامه خلاصهای از دستورهای پشتیبانیشده آمده است (در مورد دستورهای set رشته کج (italic) داخل گیومه با مقدار موجود در توضیحات جایگزین میشود. در مورد دستورهای get رشته کج داخل گیومه نام کلید مقدار بازگرداندهشده است):
- F, set_freq 'Frequency'
- تنظیم 'Frequency' (فرکانس) به هرتز (Hz).
- فرکانس میتواند یک مقدار عدد ممیز شناور یا عدد صحیح باشد.
- f, get_freq
- دریافت 'Frequency' به هرتز (Hz).
- یک مقدار عدد صحیح را بازمیگرداند.
- l, get_level 'Level'
- دریافت 'Level Value' (مقدار سطح).
- مقدار سطح (Level Value) را به صورت عدد اعشاری یا عدد صحیح برای توکن Level دادهشده بازمیگرداند.
- نکته: ارسال ‘?’ (پرسوجو) به عنوان آرگومان نخست به جای توکن Level، فهرستی جداشده با فاصله از توکنهای get level پشتیبانیشده توسط بکاند تقویتکننده را برمیگرداند. از این مورد برای تشخیص سطوح پشتیبانیشده توسط یک بکاند تقویتکننده مشخص استفاده کنید.
- dump_state
- بازگرداندن اطلاعات وضعیت مشخصی درباره بکاند تقویتکننده.
- 1, dump_caps
- این یک دستور راه دور (remote) واقعی تقویتکننده نیست، صرفاً قابلیتها را تخلیه (dump) میکند، یعنی آنچه بکاند درباره این مدل میداند و کارهایی که میتواند انجام دهد.
- TODO: اطمینان حاصل شود که این خروجی ساختار ثابتی دارد تا بتوان آن را در یک hash، دیکشنری یا موارد مشابه خواند. لطفاً گزارشهای اشکال را ارسال کنید.
- نکته: این دستور خطوط خروجی زیادی تولید خواهد کرد، بنابراین اگر از آرایهای با طول ثابت استفاده میکنید بسیار مراقب باشید! به عنوان مثال، اجرای این دستور در برابر بکاند Dummy خطوط متعددی از خروجی متنی تولید میکند.
- _, get_info
- بازگرداندن اطلاعات از بکاند تقویتکننده.
- R, reset 'Reset'
- انجام 'Reset' تقویتکننده.
- مقدار Reset یک عدد صحیح است: ‘0’ = هیچکدام (None)، ‘1’ = بازنشانی حافظه (Memory reset)، ‘2’ = بازنشانی خطا (Fault reset)، ‘3’ = بازنشانی تقویتکننده (Amplifier reset).
- set_powerstat 'Power Status'
- تنظیم 'Power Status' (وضعیت توان/برق).
- مقدار Power Status یک عدد صحیح است: ‘0’ = خاموش (Power Off)، ‘1’ = روشن (Power On)، ‘2’ = آمادهبهکار (Power Standby - ورود به وضعیت standby)، ‘4’ = عملیاتی (Power Operate - خروج از وضعیت standby).
- get_powerstat
- دریافت 'Power Status' همانند set_powerstat در بالا. دو پروتکل توسط ampctld مورد استفاده قرار میگیرند: پروتکل پیشفرض و پروتکل پاسخ گسترده (Extended Response Protocol).
پروتکل پیشفرض در درجه اول برای برقراری ارتباط میان توابع کتابخانه Hamlib و ampctld (“NET ampctl”، در دسترس با استفاده از مدل تقویتکننده ‘2’) در نظر گرفته شده است.
پروتکل پاسخ گسترده برای استفاده در اسکریپتها یا سایر برنامههایی که مستقیماً با ampctld در تعامل هستند در نظر گرفته شده است، چرا که بازخورد یکپارچه و پایداری ارائه میدهد.
پروتکل پیشفرض (Default Protocol)
پروتکل پیشفرض عمداً ساده طراحی شده است. دستورها به همراه هر مقدار مورد نیاز در یک خط وارد میشوند. در عمل، با پایان دادن به هر رشته دستور با یک نویسه خطجدید، یعنی ‘\n’، نتایج قابل اطمینانی به دست میآید.
مثال دستورهای تنظیم فرکانس و حالت (کد Perl (متن تایپشده بهصورت پررنگ نشان داده شده است)):
print $socket "F 14250000\n"; print $socket "\\set_powerstat 1\n"; # escape leading '\'
یک پاسخ تکخطی در جواب دستورهای set ارسال خواهد شد: “RPRT x\n” که در آن x کد خطای Hamlib است و ‘0’ نشاندهنده موفقیت دستور است.
پاسخها از دستورهای get در ampctld مقادیر متنی هستند و با همان نشانههای استفادهشده در دستورهای set مطابقت دارند. هر مقدار در یک خط جداگانه بازگردانده میشود. در صورت بروز خطا، رشته “RPRT x\n” بازگردانده میشود که در آن x کد خطای Hamlib است.
مثال دریافت فرکانس (کد Perl):
print $socket "f\n"; "14250000\n"
بیشتر توابع get یک تا سه مقدار را بازمیگردانند. یک استثنای قابل توجه دستور dump_caps است که خطوط متعددی از جفتهای key:value را بازمیگرداند.
این پروتکل عمدتاً توسط بکاند “NET ampctl” (مدل ۲ ampctl) استفاده میشود که به برنامههایی که پیشتر برای C API مربوط به Hamlib نوشته شدهاند امکان میدهد بدون نیاز به بازنویسی کد برنامه، از ampctld بهره ببرند. کاربر برنامه میتواند مدل تقویتکننده ۲ (“NET ampctl”) را انتخاب کرده و سپس amp_pathname را روی “localhost:4531” یا سایر host:port های شبکه (که به ترتیب با گزینههای -T/-t در بالا تنظیم میشوند) قرار دهد. پروتکل پاسخ گسترشیافته چندین قاعده به رشتههای بازگردانده شده توسط ampctld و یک قاعده به نحو دستورات اضافه میکند.
۱. دستوری که توسط ampctld دریافت میشود، با نام طولانی دستور و به دنبال آن مقدار(ها)یی (در صورت وجود) که از کلاینت دریافت شده و با جداکننده پاسخ مشخصشده پایان مییابد، به عنوان نخستین رکوردِ پاسخ بازتاب داده میشود (echo).
۲. آخرین رکورد هر بلوک رشتهی “RPRT x\n” است که در آن x مقدار بازگشتی عددی از تابع بکاند Hamlib است که توسط دستور فراخوانی شده است.
۳. هر رکوردی شامل مقادیر داده که توسط بکاند تقویتکننده (amplifier) بازگردانده میشود، با یک رشته آغاز شده و بلافاصله پس از آن دونقطه و سپس یک فاصله و در نهایت مقدارِ پایانیافته با جداکننده پاسخ قرار میگیرد. مانند “Frequency: 14250000\n” هنگامی که در ابتدای دستور ‘+’ قرار گرفته باشد.
۴. تمامی دستورهای دریافت شده توسط ampctld با رکوردهای حاصل از قوانین ۱ و ۲ تأیید (acknowledge) خواهند شد. رکوردهای حاصل از قانون ۳ تنها زمانی بازگردانده میشوند که لازم باشد مقادیر داده به کلاینت بازگردانده شوند.
یک نمونه پاسخ به دستور set_frequency ارسالشده از خط فرمان شل (به ‘+’ ابتدایی دقت کنید):
$ echo "+F 14250000" | nc -w 1 localhost 4531 set_freq: 14250000 RPRT 0
در این حالت، نام طولانی دستور و مقادیر در خط نخست بازگردانده میشوند و خط دوم شامل نشانگر پایان بلوک و مقدار بازگشتی عددی بکاند تقویتکننده است که نشاندهنده موفقیتآمیز بودن است.
یک نمونه پاسخ به پرسمان get_freq:
$ echo "+\get_freq" | nc -w 1 localhost 4531 get_freq: Frequency(Hz): 14250000 RPRT 0
- نکته: نویسه ‘\’ حتی همراه با نویسه ERP همچنان برای نام طولانی دستور الزامی است.
در این حالت، چون مقداری به ampctld ارسال نشده است، خط نخست تنها شامل نام طولانی دستور است. خط پایانی نشان میدهد که دستور با موفقیت توسط بکاند تقویتکننده پردازش شده است.
فراخوانی پروتکل پاسخ گسترشیافته مستلزم قرار دادن یک نویسه نشانهگذاری (punctuation) در ابتدای دستور است. همانطور که در مثالهای بالا نشان داده شد، قرار دادن نویسه ‘+’ در ابتدای دستور باعث میشود پاسخها با یک نویسه خط جدید (‘\n’) از هم جدا شوند. هر نویسه نشانهگذاری دیگری که توسط تابع ispunct() در زبان C شناخته شود به جز ‘\’، ‘?’ یا ‘_’، باعث میشود آن نویسه به عنوان جداکننده پاسخ در نظر گرفته شده و تمام پاسخ در یک خط قرار گیرد.
خلاصه نویسههای جداکننده:
- ‘+’
- به هر رکورد از پاسخ یک خط جدید (‘\n’) افزوده میشود.
- ‘;’، ‘|’ یا ‘,’
- به هر رکورد پاسخ نویسه مشخصشده افزوده میشود که منجر به قرار گرفتن کل پاسخ در یک خط میگردد.
- اینها جداکنندههای رایج رکورد برای نمایش متنی دادههای صفحات گسترده (spreadsheet) و غیره هستند.
- ‘?’
- برای راهنما در ampctl رزرو شده است.
- ‘_’
- برای دستور کوتاه get_info رزرو شده است.
- ‘#’
- برای توضیحات (کامنتها) هنگام خواندن اسکریپت فایل دستور رزرو شده است.
- نکته: سایر نویسههای نشانهگذاری آزمایش نشدهاند! استفاده از آنها با مسئولیت خودتان است.
برای نمونه، فراخوانی یک پرسمان get_freq با یک ‘;’ در ابتدا بازمیگرداند:
get_freq:;Frequency(Hz): 14250000;RPRT 0
یا با استفاده از نویسه خط لوله (pipe) ‘|’ بازمیگرداند:
get_freq:|Frequency(Hz): 14250000|RPRT 0
و یک دستور set_freq که با ‘|’ آغاز شده باشد بازمیگرداند:
set_freq: 14250000|RPRT 0
چنین قالبی امکان خواندن یک پاسخ را به عنوان یک رویداد واحد با استفاده از جداکننده پاسخ دلخواه فراهم میآورد. سایر نویسههای نشانهگذاری آزمایش نشدهاند! گزینه -v یا --verbose امکان ارسال سطوح مختلف پیامهای عیبیابی به stderr را فراهم میکند که به این ترتیب متناظر هستند: -v برای BUG، -vv برای ERR، -vvv برای WARN، -vvvv برای VERBOSE، یا -vvvvv برای TRACE.
یک سطح پرحرفی (verbose) مشخص برای ارائه اطلاعات اشکالزداییِ مورد نیاز به نشانی ایمیل زیر مفید است. برای نمونه، خروجی TRACE تمام مقادیر ارسالشده به تقویتکننده و دریافتشده از آن را نشان میدهد که برای توسعه کتابخانه بخش پشتی (backend) تقویتکننده بسیار سودمند است و ممکن است توسط توسعهدهندگان درخواست شود.
مثالها (EXAMPLES)
راهاندازی ampctld برای یک Elecraft KPA-1500 با استفاده از مبدل USB به سریال و اجرای آن در پسزمینه:
$ ampctld -m 201 -r /dev/ttyUSB1 &
راهاندازی ampctld برای یک Elecraft KPA-1500 با استفاده از COM2 در MS Windows:
$ ampctld -m 201 -r COM2
اتصال به ampctld در حال اجرا و تنظیم فرکانس روی 14.266 MHz با مهلت زمانی خواندن ۱ ثانیه، با استفاده از پروتکل پیشفرض از اعلان پوسته:
$ echo "\set_freq 14266000" | nc -w 1 localhost 4531
اتصال به یک ampctld در حال اجرا با ampctl روی میزبان محلی:
$ ampctl -m2
امنیت (SECURITY)
هیچگونه احراز هویتی وجود ندارد؛ هرگز این درگاه TCP را بدون محافظت بر روی اینترنت باز نگذارید. لطفاً در صورت نیاز به امنیت قویتر درخواست دهید یا استفاده از تونل Secure Shell (ssh(1)) را در نظر بگیرید.
از آنجا که ampctld به مجوزهایی بیشتر از ampctl نیاز ندارد، توصیه میشود برای محدود کردن هرگونه آسیبپذیری، ampctld با کاربر “root” یا حساب کاربری سیستمی دیگری اجرا نشود. این دیمن خود را از پایانه جدا نکرده و به پسزمینه منتقل نمیشود.
هیچ روشی برای خروج از دیمن وجود ندارد، بنابراین برای خاتمه دادن به آن باید از دستور kill(1) استفاده شود.
چندین کلاینت که از این دیمن استفاده میکنند ممکن است در دسترسی به تقویتکنندهٔ متصل دچار رقابت و تداخل شوند.
گزارش باگها به:
کپیرایت و تکثیر (COPYING)
این فایل بخشی از Hamlib است؛ پروژهای برای توسعه کتابخانهای که توابع کنترلی رادیو، چرخاننده و تقویتکننده را برای توسعهدهندگان نرمافزارهایی که عمدتاً مورد توجه آماتورهای رادیویی و علاقهمندان به ارتباطات رادیویی هستند، سادهسازی میکند.
حق نشر © 2000-2010
Stephane Fillod
حق نشر © 2000-2018
گروه Hamlib
(مشارکتکنندگان
گوناگون)
حق نشر © 2011-2020 Nate Bargmann
این یک نرمافزار آزاد است؛ برای شرایط تکثیر، فایل COPYING را ببینید. هیچگونه ضمانتی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.
همچنین ببینید (SEE ALSO)
شناسنامه (COLOPHON)
پیوندها به ویکی Hamlib، مخزن Git، بایگانیهای انتشار و بایگانیهای تصویر روزانه (daily snapshot) از طریق نشانی زیر در دسترس هستند: hamlib.org.
| 2020-09-09 | Hamlib |