diff --git a/doc/Makefile.am b/doc/Makefile.am index 835b117b7..9a6c6e5ff 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -2,7 +2,8 @@ EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html \ Hamlib_design.eps Hamlib_design.png dist_man_MANS = man1/rigctl.1 man1/rigctld.1 man1/rigmem.1 man1/rigsmtr.1 \ - man1/rigswr.1 man1/rotctl.1 man1/rotctld.1 + man1/rigswr.1 man1/rotctl.1 man1/rotctld.1 man7/hamlib.7 \ + man7/hamlib-primer.7 man7/hamlib-utilities.7 htmldir = $(docdir)/html dist_html_DATA = Hamlib_design.png hamlib.html diff --git a/doc/man7/hamlib-primer.7 b/doc/man7/hamlib-primer.7 new file mode 100644 index 000000000..dea2ee5af --- /dev/null +++ b/doc/man7/hamlib-primer.7 @@ -0,0 +1,838 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" +.\" For layout and available macros, see man(7), man-pages(7), groff_man(7) +.\" Please adjust the date whenever revising the manpage. +.\" +.\" Please keep this file in sync with doc/getting_started.texi +.\" +.TH HAMLIB-PRIMER "7" "2018-05-27" "Hamlib" "Hamlib Information Manual" +. +. +.SH NAME +. +hamlib-primer \- compiling and using the radio and rotator control library +. +. +.SH DESCRIPTION +. +There are several ways to obtain a working installation of Hamlib. +. +The following sections discuss installing from a package manager, building +from source, and installing Hamlib project supplied binaries on Microsoft +Windows\*R. +. +. +.SS Installing binary packages on Linux and BSD +. +The easiest way to install a released version of Hamlib on a Linux based +distribution or a BSD variant is through the provided +.IR "package manager" . +. +While package managers vary according to the distribution (it's easy to lump +BSD variants in this group too) their end goal is to provide ready to use +software packages. +. +Since such a wide variety of package managers exist, it is best to recommend +that the documentation for your chosen distribution be your guide. +. +. +.SS A variety of Hamlib sources +. +Distribution packages are most often official Hamlib releases and in some +cases could be quite old and lacking support for newer radios or rotators. +. +In some cases support is improved in existing radio or rotator back ends and +bugs are fixed in newer releases. +. +Often times to get the improved support/bug fixes, building from source will +be required. +. +Relax, it's not hard. :-) +. +.PP +Source code is available as official releases, testing snapshots, daily +development snapshots, and the bleeding edge of development directly from the +.UR https://github.com/Hamlib/Hamlib +Git repository +.UE . +. +As a rule, even the bleeding edge tarballs should configure and compile +without error even though certain implementation work may be in progress and +may be incomplete or have errors. +. +. +.SS Getting released source +. +. +Official Hamlib source releases, commonly called +.I tarballs +can be +found on the +.UR http://sourceforge.net/projects/hamlib/files/hamlib/ +SourceForge.net Hamlib files +.UE +Web page. +. +As a convenience, release archives are also mirrored at the +.UR https://github.com/Hamlib/Hamlib/releases +GitHub Hamlib releases +.UE +page. +. +The most recent release is listed first. +. +. +.SS Getting source snapshots +. +Testing release candidates (RCs) are posted during the period (often a few +weeks) before a planned release. +. +Beginning with the 3.2 release, RCs are hosted by the +.UR https://github.com/Hamlib/Hamlib/releases +GitHub release archive +.UE . +. +RCs are identifed by having a +.I ~rc +suffix. +. +.PP +Daily snapshots of the development repository are available via the World Wide +Web from +.UR http://n0nb.users.sourceforge.net/ +Hamlib Git daily snapshots +.UE . +. +These are not official releases but are provided for testing new features and +bug fixes. +. +.PP +The daily development snapshot is made and posted each day by around 1030 UTC. +. +Daily snapshots +.I should +compile but sometimes a bug creeps in that prevents compilation. +. +If that should happen, please report it to the +.MT hamlib-developer@@lists.sourceforge.net +hamlib-developer mailing list +.ME . +. +. +.SS Git repository +. +The source repository can be +.I cloned +which copies the repository to your computer including its entire history, +branches, and release tag information. +. +In other words, once the +.BR git "(1) " clone +command is finished a complete copy of the Hamlib development will be on your +computer. +. +You can do quite a lot with this as nothing is hidden from view since the +entire history of Hamlib is right there all the way from the very first commit +to the present. +. +None of the meta-data is hidden away on some central server. +. +.PP +To clone the repository use the following command: +. +.sp +.RS 0.5i +.EX +git clone https://git.code.sf.net/p/hamlib/code hamlib +.EE +.RE +. +.PP +or: +.sp +.RS 0.5i +.EX +git clone https://github.com/Hamlib/Hamlib.git +.EE +.RE +. +.PP +. +Odds are that you will want to run the above command in a sub directory of +your home directory. +. +The +.I hamlib +directory will be created by Git and the +.I master +branch will be checked out for you as the +.IR "working copy" . +. +The master branch is one of several branches used in Hamlib development. +. +It is the main branch of new features and bug fixes. +. +The working copy will be the latest revision of every file at the time of the +clone. +. +Later updates from the developers will require using another Git command to +update your local repository. +. +. +.SS Building from source +. +Building from source will be required for various reasons. +. +Perhaps only an older release is provided by your distribution, or you would like +to test recent changes to Hamlib\(emeither a specific back end or API +changes\(emand offer a report to the developers, or you would like to take part in +development and offer your contribution to the project, or you would just like to +learn how to build a relatively comprehensive package from source. +. +Any is a good reason to build from the source code archive. +. +.PP +Before going further, this manual assumes familiarity with working from the +command prompt in a Linux/BSD/Unix like system's +.I shell +environment, either in a +.I virtual console +(a text only screen with no graphics) or in a +.I terminal +in a desktop environment +.RB ( xterm , +.BR rxvt , +.BR konsole , +.BR gnome\-terminal , +.BR xfce4\-terminal , +.BR terminal , +etc.). +. +If this is new to you, take some time and read up on using the shell. +. +A good tutorial can be found at +.UR http://linuxcommand.org/ +LinuxCommand.org +.UE +which also offers an in-depth book that can be purchased or downloaded for no +cost (the Hamlib project is not associated with nor has any interest in the +sale of this book, it just looks like a very good effort on the part of its +author). +. +.PP +Let's get started. +. +. +.SS Compiling source tarballs +. +Before proceeding, it is essential to read the information in the files, +.IR README , +.IR INSTALL , +and +.I README.betatester +supplied in the Hamlib +.I top-level +directory which will be named +something like +.I hamlib-3.3~git +where the latter part is the release version. +. +In this case the +.I 3.3~git +indicates this is a development snapshot of the Git master branch. +. +These files provide detailed information for compiling Hamlib and will vary +some from release to release. +. +.PP +Compiling from a source tarball whether it is an official release or a testing +or daily development snapshot follows the same set of commands, known as the +.I three step +which are each run from the top-level directory: +. +.sp +.RS 0.5i +.EX +\&./configure +make +sudo make install +.EE +.RE +. +.SS configure +. +The +.IB ./ configure +command examines your system and checks it for any packages that are required +or good to have options for compiling Hamlib. +. +The leading +.I ./ +tells the shell to only run the +.B configure +command found in the current directory. +. +It is always possible that a +.B configure +command could be lurking elsewhere and we don't want to run that! +. +.PP +Run: +. +.sp +.RS 0.5i +.EX +\&./configure +.EE +.RE +. +.PP +from the top-level directory. +. +.IP +.BR Note : +Some distributions are configured so commands can only be run from directories +listed in the +.B PATH +environment variable. +. +The +.I ./ +is necessary or the +.B configure +command will not be run as the +.I current directory +(defined as +.IR . ) +is not in the +.BR PATH . +. +This is considered a default security feature so that only programs provided +by the distribution are run. +. +.B PATH +can be modified for your own session, but that is a topic for the +LinuxCommand.org reference above. +. +.PP +Of course, things are usually complicated a bit by options and Hamlib is no +exception. +. +The good news is that the defaults, i.e., no options, work well in most +situations. +. +Options are needed to enable the compilation of certain portions of Hamlib +such as the language bindings. +. +Optional features usually require that more development tools are installed. +. +The +.I INSTALL +and +.I README.betatester +files in the Hamlib top-level directory will have details on the options +available for that release. +. +.PP +A useful option is +.B \-\-prefix +which tells +.B configure +where in the file system hierarchy Hamlib should be installed. +. +If it is not given, Hamlib will be installed in the +.I /usr/local +file system hierarchy. +. +Perhaps you want to install to your home directory instead: +. +.sp +.RS 0.5i +.EX +\&./configure \-\-prefix=$HOME/local +.EE +.RE +. +.IP +.BR Note : +For practice you may wish to start out using the +.BR \-\-prefix = \fI$HOME/local\fP +option to install the Hamlib files into your home directory and avoid +overwriting any version of Hamlib installed into the system directories. +. +The code examples in the remainder of this manual will assume Hamlib has been +installed to +.IR $HOME/local . +. +.PP +All of the files will be installed in the +.I local +directory of your home directory. +. +.I local +will be created if it does not exist during installation as will several other +directories in it. +. +Installing in your home directory means that +.IR root , +or superuser (administrator) privileges are not required when running +.BR "make install" . +. +On the other hand, some extra work will need to be done so other programs can +use the library. +. +.\" (TODO: describe library hackery in an appendix). +. +.PP +Another useful option is +.B \-\-help +which will give a few screens full of options for +.BR configure . +. +If in a desktop environment the scroll bar can be used to scroll back up +through the output. +. +In either a terminal or a virtual console Linux supports the Shift\-PageUp key +combination to scroll back up. +. +Conversely, Shift\-PageDown can be used to scroll down toward the end of the +output and the shell prompt (Shift\-UpArrow/Shift\-DownArrow may also work to +scroll one line at a time). +. +.PP +After a fair amount of time, depending on your computer, and a lot of screen +output, +.B configure +will finish its job. +. +So long as the few lines previous to the shell prompt don't say \(lqerror\(rq +or some such failure message Hamlib is ready to be compiled. +. +If there is an error and all of the required packages listed in +.I README.betatester +have been installed, please ask for help on the +.MT hamlib\-developer@@lists.sourceforge.net +hamlib-developer mailing list +.ME . +. +. +.SS make +. +The +.BR make (1) +command is responsible for running the +.I compiler +which reads the source files and from the instructions it finds in them writes +.I object +files which are the binary instructions the CPU of a computer can execute. +. +.B make +then calls the +.I linker +which puts the object files together in the correct order to create the Hamlib +library files and its executable programs. +. +.PP +Run: +. +.sp +.RS 0.5i +.EX +make +.EE +.RE +. +.PP +from the top-level directory. +. +.PP +Any error that causes +.B make +to stop early is cause for a question to the +.MT hamlib\-developer@@lists.sourceforge.net +hamlib-developer mailing list +.ME . +. +.PP +In general +.B make +will take longer than +.B configure +to complete its run. +. +As it is a system command, and therefore found in the +.BR PATH , +prefixing +.B make +with +.I ./ +will cause a \(lqcommand not found\(rq error from the shell. +. +. +.SS make install +. +Assuming that you have not set the installation prefix to your home directory, +root (administrator) privileges will be required to install Hamlib to the +system directories. +. +Two popular methods exist for gaining root privileges, +.BR su (1) +and +.BR sudo (8). +. +.B sudo +is probably the most popular these days, particularly when using the +.UR http://www.ubuntu.com +Ubuntu +.UE +family of distributions. +. +.PP +Run: +. +.sp +.RS 0.5i +.EX +sudo make install +.EE +.RE +. +.PP +as root from the top-level directory. +. +.PP +Running +.B make install +will call the installer to put all of the newly compiled files and other files +(such as this document) in predetermined places set by the +.B \-\-prefix +option to +.B configure +in the directory hierarchy (yes, this is by design and +.B make +is not just flinging files any old place!). +. +.PP +A lot of screen output will be generated. +. +Any errors will probably be rather early in the process and will likely be +related to your +.I username +not having write permissions in the system directory structure. +. +. +.SS ldconfig +. +Once the installation is complete one more step is required if Hamlib has +never been installed from a local build before. +. +The +.B ldconfig +command tells the system library loader where to find the newly installed +Hamlib libraries. +. +It too will need to be run with root privileges: +. +.PP +Run: +. +.sp +.RS 0.5i +.EX +sudo ldconfig +.EE +.RE +. +.PP +as root from any directory. +. +.PP +.BR Note : +Subsequent installations of Hamlib will not need to have +.B ldconfig +run after each installation if a newer version of Hamlib was not installed, +i.e. when recompiling the same version during development. +. +.PP +On some distributions a bit of configuration will be needed before +.B ldconfig +will add locally compiled software to its database. +. +Please consult your distribution's documentation. +. +. +.SS Bootstrapping from a \(aqgit clone\(aq +. +Choosing to build from from a +.B git clone +requires a few more development tools (notice a theme here?) as detailed in +.IR README.developer . +. +The most critical will be the GNU Autotools +.RB ( autoconf , +.BR automake , +.BR libtool , +and more) from which the build system consisting of +.BR configure , +the various +.IR Makefile.in s +throughout the directory structure, and the final +.IR Makefile s +are generated. +. +.PP +In the top-level directory is the +.B bootstrap +script from which the build system is +.IR bootsrapped\(emthe +process of generating the Hamlib build system from +.I configure.ac +and the various +.IR Makefile.am s. +. +At its completion the +.B configure +script will be present to configure the build system. +. +.PP +Next +.B configure +is run with any needed build options +.RB ( "configure \-\-help" +is useful) to enable certain features or provide paths for locating needed +build dependencies, etc. +. +Environment variables intended for the preprocessor and/or compiler may also +be set on the +.B configure +command line. +. +.PP +After the configuration is complete, the build may proceed with the +.B make +step as for the source tarballs above. +. +Or +.B configure \-\-help +may be run, and +.B configure +run again with specific options in which case the +.IR Makefile s +will be regenerated and the build can proceed with the new configuration. +. +. +.SS Other make targets +. +Besides +.BR "make install" , +other +.I targets +exist when running +.BR make . +. +Running +.B make clean +from the top-level directory removes all of the generated object and +executable files generated by running +.B make +freeing up considerable disk space. +. +.PP +.BR Note : +During development of individual source files, it is not necessary to +run +.B make clean +each time before +.BR make . +. +Simply run +.B make +and only the modified file(s) and any objects that depend on them will be +recompiled. +. +This speeds up development time considerably. +. +.PP +To remove even the generated +.IR Makefile s, +run +.B make distclean +from the top-level directory. +. +After this target is run, +.B configure +will need to be run again to regenerate the +.IR Makefile s. +. +This command may not be as useful as the +.IR Makefile s +do not take up much space, however it can be useful for rebuilding the +.IR Makefile s +when modifying a +.I Makefile.am +or +.I confgure.ac +during build system development. +. +. +.SS Parallel build trees +. +One feature of the GNU build system used by Hamlib is that the object files +can be kept in a directory structure separate from the source files. +. +While this has no effect on the +.B make +targets described above, it does help the developer find files in the source +tree! +. +One such way of using parallel builds is described in +.IR README.developer . +. +.PP +Parallel builds can be very useful as one build directory can be configured +for a release and another build directory can be configured for debugging with +different options passed to +.B configure +from each directory. +. +The generated +.IR Makefile s +are unique to each build directory and will not interfere with each other. +. +. +.SS Adding debugging symbols +. +When additional debugging symbols are needed with, for example, the GNU +Debugger, +.BR gdb , +the needed compiler and linker options are passed as environment variables. +. +.PP +Run: +.sp +.RS 0.5i +.EX +\&../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0" +.EE +.RE +. +.PP +from a sibling build directory intended for a debugging build. +. +.PP +The +.B \-ggdb3 +option tells the C compiler, in this case the GNU C Compiler, +.BR gcc , +to add special symbols useful for GDB, the GNU debugger. +. +The +.B -O0 +option tells +.B gcc +to turn off all optimizations which will make it easier to follow some +variables that might otherwise be optimized away. +. +.B CFLAGS +and +.B CXXFLAGS +may be set independently for each compiler. +. +.PP +.BR Note : +There are a number compiler options available for controlling debugging +symbols and setting optimization levels. +. +Please consult the compiler's manual for all the details. +. +. +.SS Compiling for Microsoft Windows +. +Currently compiling is done on a Debian 8 (Jessie) virtual machine using +.UR http://www.mingw.org +MinGW +.UE . +.I README.build-win32 +in the +.I scripts +directory has details on how this is accomplished. +. +. +.SS Pre-compiled binaries for Microsoft Windows +. +Pre-compiled binaries for Microsoft Windows 32 and 64 bit architectures +(Windows NT and newer) are available for both official releases and daily +development snapshots. +. +Official releases are available through the +.UR http://sourceforge.net/projects/hamlib/files/hamlib/ +SourceForge.net file download service +.UE . +. +As an alternative, official releases are also available though the +.UR https://github.com/Hamlib/Hamlib/releases +Hamlib archive at GitHub +.UE . +. +Daily development snapshots are available from the +.UR http://n0nb.users.sourceforge.net/ +daily snapshots page +.UE . +. +.PP +Beginning with the Hamlib 1.2.15.3 release a self-extracting installer is +available. +. +Among its features are selecting which portions of Hamlib are installed. +. +The +.B PATH +environment variable will need to be set manually per the included +.I README.w32-bin +or +.I README.w64-bin +file. +. +.PP +Daily development snapshots feature both a .ZIP archive and the self +extracting installer. +. +.PP +Bug reports and questions about these archives should be sent to the +.MT hamlib-developer@@lists.sourceforge.net +hamlib-developer mailing list +.ME . +. +. +.SH COPYING +. +This file is part of Hamlib, a project to develop a library that simplifies +radio and rotator control functions for developers of software primarily of +interest to radio amateurs and those interested in radio communications. +. +.PP +Copyright \(co 2001-2018 Hamlib Group (various contributors) +. +.PP +This is free software; see the file COPYING for copying conditions. There is +NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +. +. +.SH SEE ALSO +. +.BR git (1), +.BR hamlib (7), +.BR ldconfig (8), +.BR make (1), +.BR su (1), +.BR sudo (8) +. +. +.SH COLOPHON +. +Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot +archives: +.IP +.UR http://www.hamlib.org +hamlib.org +.UE . diff --git a/doc/man7/hamlib-utilities.7 b/doc/man7/hamlib-utilities.7 new file mode 100644 index 000000000..8b369c08f --- /dev/null +++ b/doc/man7/hamlib-utilities.7 @@ -0,0 +1,835 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" +.\" For layout and available macros, see man(7), man-pages(7), groff_man(7) +.\" Please adjust the date whenever revising the manpage. +.\" +.\" Please keep this file in sync with doc/utility-programs.texi +.\" +.TH HAMLIB-UTILITIES "7" "2018-05-27" "Hamlib" "Hamlib Information Manual" +. +. +.SH NAME +. +hamlib-utilties \- radio and rotator control utilities of Hamlib +. +. +.SH DESCRIPTION +. +Included with the Hamlib distribution are several utility programs. +. +Besides providing a way for developers to test new code and bug fixes, the +programs also offer a reference implementation for interfacing to the Hamlib +library functions both through the +.B C +.SM API +(Application Programming Interface) and offering a network accessible +.SM API. +. +.PP +This page summarizes the two test programs, +.BR rigctl (1) +for testing radio back ends and +.BR rotctl (1) +for testing rotator back ends and the two network daemons, +.BR rigctld (1) +and +.BR rotcltd (1) +for radio and rotator access via network sockets. +. +Also included are three demonstation utilities, +.BR rigmem (1), +.BR rigsmtr (1), +and +.BR rigswr (1) +which provide functional examples of how Hamlib may be used to accomplish +various tasks. +. +. +.SH rigctl +. +.BR rigctl (1) +is the most frequently used Hamlib utility. +. +As the other +.I ctl +utilities share many of the same characteristics, much of the introductory +information presented in this section is applicable to the other utility +programs. +. +. +.SS Introduction to rigctl +. +Most likely the first of the Hamlib utility programs that is used is +.BR rigctl (1). +. +rigctl is a character based interactive program and a command line program +able to set or query a radio's value with a single command. +. +rigctl is invoked from a shell command prompt with various options and +additional commands. +. +.PP +In its most simple use as a +.I "command line" +program, rigctl is used to set frequency and mode by typing commands after any +rigctl options: +. +.sp +.RS 0.5i +.EX +rigctl F 14205000 +.br +rigctl M USB 2400 +.EE +.RE +. +.PP +and then query those values: +. +.sp +.RS 0.5i +.EX +rigctl f +.br +rigctl m +.EE +.RE +. +.PP +Entering +.I "interactive mode" +is a simple matter of not placing any commands after any rigctl options: +. +.sp +.RS 0.5i +.EX +rigctl +.EE +.RE +. +.PP +Entering interactive mode allows successive commands to be entered without +exiting rigctl. +. +Recent additions to rigctl allow command editing and history recall through +use of the +.UR https://tiswww.case.edu/php/chet/readline/rltop.html +Readline +.UE +library. +. +.PP +Interactive mode is indicated by the spartan prompt: +. +.sp +.RS 0.5i +.EX +Rig command: +.EE +.RE +. +.PP +Commands are given at the prompt and follow the general rule that upper case +letters set a value and lower case letters query a value: +. +.sp +.RS 0.5i +.EX +Rig command: M +.br +Mode: USB +.br +Passband: 2500 +.sp +Rig command: m +.br +Mode: USB +.br +Passband: 2500 +.sp +Rig command: +.EE +.RE +. +.PP +An additional prompt is printed when more information is required by the +command. +. +For \f(CWM\fP above, rigctl prompted for the \f(CWMode\fP and \f(CWPassband\fP +values. +. +For \f(CWm\fP above, rigctl returned the \f(CWMode\fP and \f(CWPassband\fP +values without further prompts. +. +The command prompt is returned after each command invocation. +. +.PP +The above examples invoked rigctl without specifying a radio model. +. +This is a feature where the Hamlib internal radio model 1 +.I dummy +is used instead. +. +The dummy radio provides a way to test Hamlib functions without the need for +actual radio hardware. +. +However, to develop the Hamlib backend capability for a given radio, having +the actual radio connected to the computer is necessary for debugging. +. +.PP +For example, to quickly set frequency on an Elecraft K3: +. +.sp +.RS 0.5i +.EX +rigctl -m 229 -r /dev/rig F 3900000 +.EE +.RE +. +.PP +and to query the frequency and then mode: +. +.sp +.RS 0.5i +.EX +rigctl -m 229 -r /dev/rig f +.br +3900000 +.sp +rigctl -m 229 -r /dev/rig m +.br +LSB +.br +2000 +.EE +.RE +. +.PP +.BR Note : +the returned values do not have the prompt strings associated with interactive +mode as shown above. +. +.PP +The +.B \-m +option takes a numeric value that corresponds to a given radio back end model. +. +The +.B \-r +option takes the path to the port device on +.SM POSIX +and the device name on Microsoft Windows. +. +.PP +.BR Note : +A complete list of supported radio models may be seen by use of the +.B -l +option: +. +.sp +.RS 0.5i +.EX +rigctl -l +.br + Rig # Mfg Model Version Status +.br + 1 Hamlib Dummy 0.5 Beta +.br + 2 Hamlib NET rigctl 0.3 Beta +.br + 101 Yaesu FT-847 0.5 Beta +.br + 103 Yaesu FT-1000D 0.0.6 Alpha +.br +\&. +.br +\&. +.br +\&. +.br + 2702 Rohde&Schwarz EB200 0.1 Untested +.br + 2801 Philips/Simoco PRM8060 0.1 Alpha +.br + 2901 ADAT www.adat.ch ADT-200A 1.36 Beta +.EE +.RE +. +.PP +The list is long so use \f(CWShift\-PageUp\fP/\f(CWShift\-PageDown\fP on +Linux, \f(CWScrollLock\fP then \f(CWPageUp\fP/\f(CWPageDown\fP on Free BSD, or +use the scrollbar to the virtual terminal window +.RB ( cmd +window on Microsoft Windows) or the output can be piped to +.BR more (1) +or +.BR less (1), +e.g. \(lq\f(CWrigctl -l | more\fP\(rq to scroll back up the list. +. +The list is sorted numerically by model number since Hamlib 1.2.15.1. +. +Model numbers of a manufacturer/protocol family are grouped together. +. +. +.SS rigctl reference +. +The complete reference for rigctl can be found in the +.BR rigctl (1) +manual page. +. +. +.SH rotctl +. +Identical in function to +.BR rigctl (1), +.BR rotctl (1) +provides a means for testing Hamlib functions useful for rotator control and +QTH (Maidenhead gridsquare system, see +.UR https://en.wikipedia.org/wiki/Maidenhead_Locator_System +Maidenhead Locator System +.UE ) +locator computations. +. +As rotators have a much narrower scope than radios, there are fewer command +line options and commands for rotctl. +. +. +.SS Introduction to rotctl +. +.BR rotctl (1) +is a character based interactive program and a command line program able to +set or query a rotator's value with a single command. +. +rotctl is invoked from a shell command prompt with various options and +additional commands. +. +.PP +In its most simple use as a +.I "command line" +program, rotctl is used to set azimuth position and (optionally) elevation by +typing commands after any rotctl options: +. +.sp +.RS 0.5i +.EX +rotctl P 145.0 23.0 +.br +rotctl M 8 25 +.EE +.RE +. +.PP +and then query those values: +. +.sp +.RS 0.5i +.EX +rotctl p +.EE +.RE +. +.PP +Entering +.I "interactive mode" +is a simple matter of not placing any commands after any rotctl options: +. +.sp +.RS 0.5i +.EX +rotctl +.EE +.RE +. +.PP +Entering interactive mode allows successive commands to be entered without +exiting rotctl. +. +Interactive mode allows for command editing and history recall through the use +of the +.UR https://tiswww.case.edu/php/chet/readline/rltop.html +Readline +.UE +library. +. +.PP +Interactive mode is indicated by the spartan prompt: +. +.sp +.RS 0.5i +.EX +Rotator command: +.EE +.RE +. +.PP +Commands are given at the prompt: +. +.sp +.RS 0.5i +.EX +Rotator command: M +.br +Direction: 16 +.br +Speed: 60 +.sp +Rotator command: p +.br +Azimuth: 11.352000 +.br +Elevation: 0.000000 +.sp +Rotator command: p +.br +Azimuth: 27.594000 +.br +Elevation: 0.000000 +.sp +Rotator command: +.EE +.RE +. +.PP +An additional prompt is printed when more information is required by the +command. +. +For \f(CWM\fP above, rotctl prompted for the \f(CWDirection\fP and +\f(CWSpeed\fP values. +. +For \f(CWp\fP above, rotctl returned the \f(CWAzimuth\fP and \f(CWElevation\fP +values without further prompts. +. +The command prompt is returned after each command invocation. +. +.PP +The above examples invoked rotctl without specifying a rotator model. +. +This is a feature where the Hamlib internal rotator model 1 +.I dummy +is used instead. +. +The dummy rotator provides a way to test Hamlib functions without the need for +actual rotator hardware. +. +However, to develop back end capability for a given rotator, having the actual +controller connected to the computer is necessary for debugging. +. +.PP +For example, to quickly set position for RotorEZ: +. +.sp +.RS 0.5i +.EX +rotctl -m 401 -r /dev/rotor P 100.0 0.0 +.EE +.RE +. +.PP +and to query the position: +. +.sp +.RS 0.5i +.EX +rotctl -m 401 -r /dev/rotor p +.br +100.000000 +.br +0.000000 +.EE +.RE +. +.PP +The returned values do not have the prompt strings associated with interactive +mode as shown above. +. +.PP +The +.B -m +option takes a numeric value that corresponds to a given rotator back end model. +. +The +.B -r +option takes the path to the port device on +.SM POSIX +or the device name on Microsoft Windows. +. +.PP +.BR Note : +A complete list of supported rotator models may be seen by use of the +.B -l +option: +. +.sp +.RS 0.5i +.EX +rotctl -l +.br + Rot # Mfg Model Version Status +.br + 1 Hamlib Dummy 0.5 Beta +.br + 2 Hamlib NET rotctl 0.3 Beta +.br + 201 Hamlib EasycommI 0.3 Beta +.br + 202 Hamlib EasycommII 0.3 Beta +.br +\&. +.br +\&. +.br +\&. +.br + 1201 AMSAT IF-100 0.1 Untested +.br + 1301 LA7LKA ts7400 0.1 Beta +.br + 1401 Celestron NexStar 0.1 Untested +.EE +.RE +. +.PP +The list is long so use \f(CWShift\-PageUp\fP/\f(CWShift\-PageDown\fP on +Linux, \f(CWScrollLock\fP then \f(CWPageUp\fP/\f(CWPageDown\fP on Free BSD, or +use the scrollbar to the virtual terminal window +.RB ( cmd +window on Microsoft Windows) or the output can be piped to +.BR more (1) +or +.BR less (1), +e.g. \(lq\f(CWrotctl -l | more\fP\(rq to scroll back up the list. +. +The list is sorted numerically by model number since Hamlib 1.2.15.1. +. +Model numbers of a manufacturer/protocol family are grouped together. +. +. +.SS rotctl reference +. +The complete reference for rotctl can be found in the +.BR rotctl (1) +manual page. +. +. +.SH rigctld +. +The +.BR rigctld (1) +program is a network server that accepts the familiar commands of +.BR rigctl (1) +and provides the response data over a +.SM TCP/IP +network socket to an application. +. +In this manner an application can access a rigctld instance from nearly +anywhere (caveat, no security is currently provided by rigctld). +. +Applications using rigctld do not link directly to Hamlib nor use its C API. +. +. +.SS Introduction to rigctld +. +.BR rigctld (1) +communicates to a client through a +.SM TCP +network socket using text commands shared with +.BR rigctl (1). +. +The protocol is simple; commands are sent to rigctld on one line and rigctld +responds to +.B get +commands with the requested values, one per line, when successful, otherwise, +it responds with one line +.B RPRT +.IR x , +where +.I x +is a negative number indicating the Hamlib error code. +. +Commands that do not return values respond with the line +.B RPRT +.IR x , +where +.I x +is zero when successful, otherwise a negative number indicating the Hamlib +error code. +. +Each line is terminated with a newline, +.IR \en , +character. +. +This protocol is primarily for use by the +.B NET rigctl +(radio model 2) backend. +. +.PP +A separate Extended Response protocol extends the above behavior by echoing +the received command string as a header, any returned values as a key: value +pair, and the +.B RPRT +.I x +string as the end of response marker which includes the Hamlib success or +failure value. +. +Consider using this protocol for clients that will interact with +rigctld directly through a TCP network socket. +. +.PP +Multiple radios can be controlled on different TCP ports by use of multiple +rigctld processes each listening on a unique TCP port. +. +It is hoped that rigctld will be especially useful for client authors using +languages such as +.UR http://www.perl.org/ +Perl +.UE , +.UR http://www.python.org/ +Python +.UE , +.UR http://php.net/ +PHP +.UE , +.UR http://www.ruby-lang.org/en/ +Ruby +.UE , +.UR http://www.tcl.tk/ +TCL +.UE , +and others. +. +. +.SS rigctld reference +. +The complete reference for rigctld can be found in the +.BR rigctld (1) +manual page. +. +. +.SH rotctld +. +The +.BR rotctld (1) +program is a network server that accepts the familiar commands of +.BR rotctl (1) +and provides the response data over a \f(CWTCP/IP\fP network socket to an +application. +. +In this manner an application can access a rotctld instance from nearly +anywhere (caveat, no security is currently provided by rotctld). +. +Applications using rotctld do not link directly to Hamlib nor use its C API. +. +. +.SS Introduction to rotctld +. +.BR rotctld (1) +communicates to a client through a +.SM TCP +network socket using text commands shared with +.BR rotctl (1). +. +The protocol is simple, commands are sent to rotctld on one line and +rotctld responds to +.B get +commands with the requested values, one per line, when successful, otherwise, +it responds with one line +.B RPRT +.IR x , +where +.I x +is a negative number indicating the Hamlib error code. +. +Commands that do not return values respond with the line +.B RPRT +.IR x , +where +.I x +is zero when successful, otherwise a negative number indicating +the Hamlib error code. +. +Each line is terminated with a newline, +.I \en +character. +. +This protocol is primarily for use by the +.B NET rotctl +(rotator model 2) backend. +. +.PP +A separate Extended Response protocol extends the above behavior by echoing +the received command string as a header, any returned values as a key: value +pair, and the +.B RPRT +.I x +string as the end of response marker which includes the Hamlib success or +failure value. +. +Consider using this protocol for clients that will interact with +rotctld directly through a TCP network socket. +. +.PP +Multiple rotators can be controlled on different TCP ports by use of multiple +rotctld processes each listening on a unique TCP port. +. +It is hoped that rotctld will be especially useful for client authors using +languages such as +.UR http://www.perl.org/ +Perl +.UE , +.UR http://www.python.org/ +Python +.UE , +.UR http://php.net/ +PHP +.UE , +.UR http://www.ruby-lang.org/en/ +Ruby +.UE , +.UR http://www.tcl.tk/ +TCL +.UE , +and others. +. +. +.SS rotctld reference +. +The complete reference for rotctld can be found in the +.BR rotctld (1) +manual page. +. +. +.SH rigmem +. +.B rigmem +may be used to backup and restore memory of radio transceivers and receivers. +. +. +.SS Introduction to rigmem +. +Backup and restore memory of radio transceivers and receivers. +.B rigmem +accepts +.IR command s +from the command line only. +. +. +.SS rigmem reference +. +The complete reference for rigmem can be found in the +.BR rigmem (1) +manual page. +. +. +.SH rigsmtr +. +.B rigsmtr +uses +.B Hamlib +to control a radio to measure S-Meter value versus antenna azimuth. +. +. +.SS Introduction to rigsmtr +. +rigsmtr rotates the antenna from minimum azimuth to maximum azimuth. +Every second, or +.I time_step +if specified in seconds, it retrieves the signal strength. Azimuth in degrees +and the corresponding S-Meter level in dB relative to S9 are then printed on +.BR stdout . +. +.PP +To work correctly, rigsmtr needs a radio that could measure S-Meter and a Hamlib +backend that is able to retrieve it, connected to a Hamlib supported rotator. +. +. +.SS rigsmtr reference +. +The complete reference for rigsmtr can be found in the +.BR rigsmtr (1) +manual page. +. +. +.SH rigswr +. +.B rigswr +may be used to measure VSWR vs frequency. +. +. +.SS Introduction to rigswr +. +rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing +Wave Ratio) over a frequency range. + +It scans frequencies from +.I start_freq +to +.I stop_freq +with an optional increment of +.I freq_step +(default step is 100 kHz). +. +All values must be entered as an integer in Hertz (cycles per second). + +.BR Note : +rigswr assumes that +.I start_freq is less than or equal to +.IR stop_freq . +. +If it is greater, rigswr will exit without doing anything. +. +.PP +For each frequency, rigswr transmits at 25% of total POWER during 0.5 second +in CW mode and reads VSWR. +. +.PP +Frequency and the corresponding VSWR are then printed on stdout. +. +.PP +To work correctly, rigswr needs a radio that can measure VSWR and a +Hamlib backend that supports reading VSWR from the radio. +. +. +.SS rigswr reference +. +The complete reference for rigswr can be found in the +.BR rigswr (1) +manual page. +. +. +.SH COPYING +. +This file is part of Hamlib, a project to develop a library that simplifies +radio and rotator control functions for developers of software primarily of +interest to radio amateurs and those interested in radio communications. +. +.PP +Copyright \(co 2001-2018 Hamlib Group (various contributors) +. +.PP +This is free software; see the file COPYING for copying conditions. There is +NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +. +. +.SH SEE ALSO +. +.BR less (1), +.BR more (1), +.BR rigctl (1), +.BR rigctld (1), +.BR rotctl (1), +.BR rotctld (1), +.BR rigmem (1), +.BR rigsmtr (1), +.BR rigswr (1), +.BR hamlib (7), +.BR hamlib-primer (7) +. +. +.SH COLOPHON +. +Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot +archives: +.IP +.UR http://www.hamlib.org +hamlib.org +.UE . diff --git a/doc/man7/hamlib.7 b/doc/man7/hamlib.7 new file mode 100644 index 000000000..58988ed83 --- /dev/null +++ b/doc/man7/hamlib.7 @@ -0,0 +1,345 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" +.\" For layout and available macros, see man(7), man-pages(7), groff_man(7) +.\" Please adjust the date whenever revising the manpage. +.\" +.\" Please keep this file in sync with doc/nutshell.texi +.\" +.TH HAMLIB "7" "2018-05-21" "Hamlib" "Hamlib Information Manual" +. +. +.SH NAME +. +hamlib \- radio and rotator control library +. +. +.SH DESCRIPTION +. +The +.BR "Ham Radio Control Libraries" , +.B Hamlib +for short, is a development effort to provide a consistent interface for +programmers wanting to incorporate radio and rotator control in their +programs. +. +.PP +Hamlib is not a complete user application, rather, it is a software layer +intended to make controlling various radios and other amateur radio station +(shack) hardware much easier. +. +Hamlib will allow authors of software such as logging programs, digital +communications programs, or those wanting to develop the ultimate radio +control software to concentrate on the user interface and the basic function +of the program rather than radio control. +. +Hamlib consists of several parts, the programming library, utility programs, +and library interfaces to other programming languages. +. +.PP +Most recent amateur radio transceivers allow external control of their +functions through a serial interface. +. +Unfortunately, control commands are not always consistent across a +manufacturer's product line and each manufacturer's product line differs +greatly from its competitors. +. +.PP +Hamlib attempts to solve this problem by presenting a +.I virtual radio +to the programmer by providing an interface to actions such as setting a given +Variable Frequency Oscillator's (VFO) frequency, setting the operating mode, +querying the radio of its current status and settings, and giving the +application a list of a given radio's capabilities. +. +Unfortunately, what can be accomplished by Hamlib is limited by the radios +themselves and some offer very limited capability. +. +.PP +Other devices, such as antenna rotators, can be placed into the Hamlib control +scheme. +. +Other recent developments include network interface servers and a USB +interface capability. +. +Language bindings are provided for +.BR C ", " C++ ", " Perl ", " Python ", " Lua " and " TCL +(more to come). +. +. +.SS Overview +. +Hamlib is a +.I front end +library providing a +.B C +language Application Programming Interface (API) to programmers wishing to +integrate radio or rotator control in their applications. +. +Hamlib presents a +.I virtual radio +or +.I virtual rotator +that is a consistent interface to an application despite wide differences in +radio and rotator interfaces and capabilities. +. +.PP +The front end library uses a number of +.I back end +libraries to translate from the front end to the various individual radio and +rotator models. +. +A back end library handles conversion of the front end variables to the format +needed by the radio or rotator device it controls. +. +The back end libraries are generally grouped by manufacturer and in some cases +by a common control protocol. +. +.PP +Hamlib also provides an interface library for each of several common +.I scripting +languages such as +.UR http://www.perl.org +.B Perl +.UE , +.UR http://www.python.org +.B Python +.UE , +.UR https://www.lua.org +.B Lua +.UE , +and +.UR http://www.tcl.tk +.B TCL +.UE . +. +These language +.I bindings +are +generated through the use of +.UR http://www.swig.org +.B SWIG +.UE , +a parser/generator for multiple language interfaces to a +.B C +library. +. +A natively generated +.B C++ +language interface is also provided. +. +.PP +Besides the C and supplemental APIs, Hamlib also provides a pair of network +daemons that provide a text command based API for controlling an attached +radio or rotator through a +.BR TCP / IP +network connection. +. +The daemons then handle the interface to the Hamlib C API. +. +.PP +More than one type of device, radio or rotator, may be controlled at a +time, however, there is generally a limit of one device per serial port +or other port. +. +. +.SS Hamlib project information +. +The Hamlib Project was founded by Frank Singleton, VK3FCS/KM5WS in July 2000. +. +Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib project and +the API and implementation development led to a reasonable level of maturity +in a few years. +. +A major milestone was reached when Hamlib 1.2.0 was released in March 2004. +. +The API and Application Binary Interface (ABI) interfaces have remained stable +since that time up to the latest release of 3.2 in early 2018. +. +.PP +Development continues through the major version number +.RI 3. x +series and beyond. +. +While some API tweaks are planned, ABI compatibility with the prior +.RI 1.2. x +releases remains a priority. +. +Other goals include streamlining the build system (done), improving the SWIG +generated language bindings (done), improving the overall documentation (this +man page with more in progress), and other updates as warranted. +. +.PP +The Project is hosted by +.UR https://sourceforge.net +SourceForge.net +.UE +at the +.UR https://sourceforge.net/projects/hamlib/ +Hamlib project page +.UE . +. +As +.UR https://github.com +GitHub +.UE +has become a very popular project hosting site, Hamlib also has a dedicated +.UR https://github.com/Hamlib/Hamlib +GitHub project page +.UE . +. +GitHub also hosts the +.UR http://www.hamlib.org +hamlib.org +.UE +Web site and the +.UR https://github.com/Hamlib/Hamlib/wiki +Hamlib Wiki +.UE . +. +.PP +Development discussion and most user support take place on the +.UR https://sourceforge.net/p/hamlib/mailman/ +hamlib-developer mailing list +.UE . +While there are +.UR https://sourceforge.net/p/hamlib/discussion/ +SourceForge.net discussion forums +.UE , +they are rarely used and not as closely read by the developers as the mailing +list. +. +.PP +For +.IR "source code management" , +the project uses +.UR http://git-scm.com/ +.B Git +.UE , +a fast, distributed content tracker. +. +Among its features is that every developer has the complete Hamlib +development history available locally. +. +For more information on using Git, see +.BR hamlib\-git (7). +. +.IP +.BR Note : +while a canonical Git repository is hosted at SourceForge, its availability is +not essential to continued development although development work flows would +change temporarily. +. +Several developers find the GitHub Web interface easier to use and lately +development has centered around GitHub rather than SourceForge. +. +. +.SS Applications using Hamlib +. +A number of application developers have taken advantage of Hamlib's +capabilities to implement radio and/or rotator control. +. +While not exhaustive, a list is maintained at the Hamlib Wiki, +.UR https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots +Applications/Screenshots +.UE . +Developers are encouraged to request their applications be added to the +gallery by way of the hamlib-developer mailing list. +. +. +.SS Using Hamlib with your program +. +As with other Free Software projects, Hamlib relies heavily on copyleft +licensing to encourage development contributions and provide an open +atmosphere for development. +. +Hamlib's source code is released under two +licenses, the +.B Lesser General Public License +(LGPL) for the library portion, and the +.B General Public License +(GPL) for the utility programs. +. +.PP +The LGPL allows the library to be used (linked) by programs regardless of +their individual license. +. +However, any contributions to the library source remain under copyleft which +means that the library source code may not be used in violation of the terms +of the LGPL. +. +.PP +The utility program source files are released under the GPL. +. +Any direct use of these sources must be in a form that complies with the terms +of the GPL. +. +Concepts learned by studying these sources for the purpose of understanding +the Hamlib API is not covered nor prohibited by the GPL, however, directly +copying GPL sources into any work that is incompatible with the terms of the +GPL is prohibited. +. +. +.SS Radios with a clone capability +. +Hamlib's focus is on controlling radios that employ a port and command +protocol for setting frequency, mode, VFO, PTT, etc. +. +Most VHF/UHF transceivers do not employ such control capability but do provide +for cloning the memory contents from radio to another of the same model. +. +A related project, +.UR http://chirp.danplanet.com +CHIRP +.UE , +aims to support radios with such a clone capability. +. +Please contact the CHIRP project for support of such radios. +. +. +.SS Pronouncing Hamlib +. +English speakers seem to have two alternate pronunciations for our project: +. +.nf +.IP \(bu 4 +Hamlib (Ham \- lib, long \(oqi\(cq, as in library.) IPA style: /\(aqham læb/ +. +.IP \(bu 4 +Hamlib (Ham \- lib, short \(oqi\(cq, as in liberty.) IPA style: /\(aqham lɪb/ +.fi +. +.PP +Then again, we have people who say Linux \(lqL-eye-nux\(rq and those who say +\(lqL-in-nux\(rq... +. +.PP +If you're French, the above does not apply! :-) +. +. +.SH COPYING +. +This file is part of Hamlib, a project to develop a library that simplifies +radio and rotator control functions for developers of software primarily of +interest to radio amateurs and those interested in radio communications. +. +.PP +Copyright \(co 2001-2018 Hamlib Group (various contributors) +. +.PP +This is free software; see the file COPYING for copying conditions. There is +NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +. +. +.SH SEE ALSO +. +.BR hamlib-primer (7) +. +. +.SH COLOPHON +. +Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot +archives: +.IP +.UR http://www.hamlib.org +hamlib.org +.UE .