1 /* 2 * Hamlib Interface - Amplifier API header 3 * Copyright (c) 2000-2005 by Stephane Fillod 4 * 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 19 * 20 */ 21 22 #ifndef _AMPLIFIER_H 23 #define _AMPLIFIER_H 1 24 25 #include <hamlib/rig.h> 26 #include <hamlib/amplist.h> 27 28 /** 29 * \addtogroup amplifier 30 * @{ 31 */ 32 33 /** 34 * \brief Hamlib amplifier data structures. 35 * 36 * \file amplifier.h 37 * 38 * This file contains the data structures and declarations for the Hamlib 39 * amplifier Application Programming Interface (API). 40 * 41 * See the amplifier.c file for details on the amplifier API functions. 42 */ 43 44 45 46 __BEGIN_DECLS 47 48 /* Forward struct references */ 49 50 struct amp; 51 struct amp_state; 52 53 54 /** 55 * \brief Main amplifier handle type definition. 56 * 57 * \typedef typedef struct amp AMP 58 * 59 * The #AMP handle is returned by amp_init() and is passed as a parameter to 60 * every amplifier specific API call. 61 * 62 * amp_cleanup() must be called when this handle is no longer needed. 63 */ 64 typedef struct amp AMP; 65 66 67 /** 68 * \brief Type definition for 69 * <a href="https://en.wikipedia.org/wiki/Standing_wave_ratio" >SWR (Standing Wave Ratio)</a>. 70 * 71 * \typedef typedef float swr_t 72 * 73 * The \a swr_t type is used as a parameter for the amp_get_swr() function. 74 * 75 * The unit of \a swr_t is 1.0 to the maximum value reported by the amplifier's 76 * internal antenna system tuner, i.e. 77 * <a href="http://www.arrl.org/transmatch-antenna-tuner" >transmatch</a>, 78 * representing the ratio of 1.0:1 to Maximum:1. 79 */ 80 typedef float swr_t; 81 82 83 /** 84 * \brief Type definition for the 85 * <a href="http://www.arrl.org/transmatch-antenna-tuner" >transmatch</a> 86 * tuning values of 87 * <a href="https://en.wikipedia.org/wiki/Capacitance" >capacitance</a> 88 * and 89 * <a href="https://en.wikipedia.org/wiki/Inductance" >inductance</a>. 90 * 91 * \typedef typedef float tune_value_t 92 * 93 * The \a tune_value_t type is used as a parameter for amp_get_level(). 94 * 95 * The unit of \a tune_value_t is 96 * <a href="https://en.wikipedia.org/wiki/Farad" >picoFarads (pF)</a> 97 * or 98 * <a href="https://en.wikipedia.org/wiki/Henry_(unit)" >nanoHenrys (nH)</a>. 99 */ 100 typedef int tune_value_t; 101 102 103 /** 104 * \brief The token in the netampctl protocol for returning an error condition code. 105 */ 106 #define NETAMPCTL_RET "RPRT " 107 108 109 //! @cond Doxygen_Suppress 110 typedef enum 111 { 112 AMP_RESET_MEM, // erase tuner memory 113 AMP_RESET_FAULT, // reset any fault 114 AMP_RESET_AMP // for kpa1500 115 } amp_reset_t; 116 //! @endcond 117 118 /** 119 * \brief Amplifier type flags 120 */ 121 typedef enum 122 { 123 AMP_FLAG_1 = (1 << 1), /*!< TBD */ 124 AMP_FLAG_2 = (1 << 2) /*!< TBD */ 125 } amp_type_t; 126 127 //! @cond Doxygen_Suppress 128 // TBD AMP_TYPE 129 #define AMP_TYPE_MASK (AMP_FLAG_1|AMP_FLAG_2) 130 131 #define AMP_TYPE_OTHER 0 132 #define AMP_TYPE_1 AMP_FLAG_1 133 #define AMP_TYPE_2 AMP_FLAG_2 134 #define AMP_TYPE_ALL (AMP_FLAG_1|AMP_FLAG_2) 135 //! @endcond 136 137 138 //! @cond Doxygen_Suppress 139 enum amp_level_e 140 { 141 AMP_LEVEL_NONE = 0, /*!< '' -- No Level. */ 142 AMP_LEVEL_SWR = (1 << 0), /*!< \c SWR 1.0 or greater. */ 143 AMP_LEVEL_NH = (1 << 1), /*!< \c Tune setting in nanohenries. */ 144 AMP_LEVEL_PF = (1 << 2), /*!< \c Tune setting in picofarads. */ 145 AMP_LEVEL_PWR_INPUT = (1 << 3), /*!< \c Power reading from amplifier. */ 146 AMP_LEVEL_PWR_FWD = (1 << 4), /*!< \c Power reading forward. */ 147 AMP_LEVEL_PWR_REFLECTED = (1 << 5), /*!< \c Power reading reverse. */ 148 AMP_LEVEL_PWR_PEAK = (1 << 6), /*!< \c Power reading peak. */ 149 AMP_LEVEL_FAULT = (1 << 7) /*!< \c Fault code. */ 150 }; 151 //! @endcond 152 153 //! @cond Doxygen_Suppress 154 #define AMP_LEVEL_FLOAT_LIST (AMP_LEVEL_SWR) 155 #define AMP_LEVEL_STRING_LIST (AMP_LEVEL_FAULT) 156 #define AMP_LEVEL_IS_FLOAT(l) ((l)&_LEVEL_FLOAT_LIST) 157 #define AMP_LEVEL_IS_STRING(l) ((l)&_LEVEL_STRING_LIST) 158 //! @endcond 159 160 /* Basic amp type, can store some useful info about different amplifiers. Each 161 * lib must be able to populate this structure, so we can make useful 162 * enquiries about capabilities. 163 */ 164 165 //! @cond Doxygen_Suppress 166 #define AMP_MODEL(arg) .amp_model=arg,.macro_name=#arg 167 //! @endcond 168 169 /** 170 * \brief Amplifier capabilities. 171 * 172 * \struct amp_caps 173 * 174 * The main idea of this struct is that it will be defined by the backend 175 * amplifier driver and will remain read-only for the application. Fields 176 * that need to be modifiable by the application are copied into the 177 * amp_state structure, which is the private memory area of the #AMP instance. 178 * 179 * This way you can have several amplifiers running within the same 180 * application, sharing the amp_caps structure of the backend, while keeping 181 * their own customized data. 182 * 183 * \b Note: Don't move fields around and only add new fields at the end of the 184 * amp_caps structure. Shared libraries and DLLs depend on a constant 185 * structure to maintain compatibility. 186 */ 187 struct amp_caps 188 { 189 amp_model_t amp_model; /*!< Amplifier model as defined in amplist.h. */ 190 const char *model_name; /*!< Model name, e.g. MM-5k. */ 191 const char *mfg_name; /*!< Manufacturer, e.g. Moonbeam. */ 192 const char *version; /*!< Driver version, typically in YYYYMMDD.x format. */ 193 const char *copyright; /*!< Copyright info (should be LGPL). */ 194 enum rig_status_e status; /*!< Driver status. */ 195 196 int amp_type; /*!< Amplifier type. */ 197 enum rig_port_e port_type; /*!< Type of communication port (serial, ethernet, etc.). */ 198 199 int serial_rate_min; /*!< Minimal serial speed. */ 200 int serial_rate_max; /*!< Maximal serial speed. */ 201 int serial_data_bits; /*!< Number of data bits. */ 202 int serial_stop_bits; /*!< Number of stop bits. */ 203 enum serial_parity_e serial_parity; /*!< Parity. */ 204 enum serial_handshake_e serial_handshake; /*!< Handshake. */ 205 206 int write_delay; /*!< Write delay. */ 207 int post_write_delay; /*!< Post-write delay. */ 208 int timeout; /*!< Timeout. */ 209 int retry; /*!< Number of retries if a command fails. */ 210 211 const struct confparams *cfgparams; /*!< Configuration parameters. */ 212 const rig_ptr_t priv; /*!< Private data. */ 213 const char *amp_model_macro_name; /*!< Model macro name. */ 214 215 setting_t has_get_level; /*!< List of get levels. */ 216 setting_t has_set_level; /*!< List of set levels. */ 217 218 gran_t level_gran[RIG_SETTING_MAX]; /*!< Level granularity. */ 219 gran_t parm_gran[RIG_SETTING_MAX]; /*!< Parameter granularity. */ 220 221 /* 222 * Amp Admin API 223 * 224 */ 225 226 int (*amp_init)(AMP *amp); /*!< Pointer to backend implementation of ::amp_init(). */ 227 int (*amp_cleanup)(AMP *amp); /*!< Pointer to backend implementation of ::amp_cleanup(). */ 228 int (*amp_open)(AMP *amp); /*!< Pointer to backend implementation of ::amp_open(). */ 229 int (*amp_close)(AMP *amp); /*!< Pointer to backend implementation of ::amp_close(). */ 230 231 int (*set_freq)(AMP *amp, freq_t val); /*!< Pointer to backend implementation of ::amp_set_freq(). */ 232 int (*get_freq)(AMP *amp, freq_t *val); /*!< Pointer to backend implementation of ::amp_get_freq(). */ 233 234 int (*set_conf)(AMP *amp, token_t token, const char *val); /*!< Pointer to backend implementation of ::amp_set_conf(). */ 235 int (*get_conf)(AMP *amp, token_t token, char *val); /*!< Pointer to backend implementation of ::amp_get_conf(). */ 236 237 /* 238 * General API commands, from most primitive to least.. :() 239 * List Set/Get functions pairs 240 */ 241 242 int (*reset)(AMP *amp, amp_reset_t reset); /*!< Pointer to backend implementation of ::amp_reset(). */ 243 int (*get_level)(AMP *amp, setting_t level, value_t *val); /*!< Pointer to backend implementation of ::amp_get_level(). */ 244 int (*get_ext_level)(AMP *amp, token_t level, value_t *val); /*!< Pointer to backend implementation of ::amp_get_ext_level(). */ 245 int (*set_powerstat)(AMP *amp, powerstat_t status); /*!< Pointer to backend implementation of ::amp_set_powerstat(). */ 246 int (*get_powerstat)(AMP *amp, powerstat_t *status); /*!< Pointer to backend implementation of ::amp_get_powerstat(). */ 247 248 249 /* get firmware info, etc. */ 250 const char *(*get_info)(AMP *amp); /*!< Pointer to backend implementation of ::amp_get_info(). */ 251 252 //! @cond Doxygen_Suppress 253 setting_t levels; 254 unsigned ext_levels; 255 //! @endcond 256 const struct confparams *extlevels; /*!< Extension levels list. \sa extamp.c */ 257 const struct confparams *extparms; /*!< Extension parameters list. \sa extamp.c */ 258 259 const char *macro_name; /*!< Amplifier model macro name. */ 260 }; 261 262 263 /** 264 * \brief Amplifier state structure. 265 * 266 * \struct amp_state 267 * 268 * This structure contains live data, as well as a copy of capability fields 269 * that may be updated, i.e. customized while the #AMP handle is instantiated. 270 * 271 * It is fine to move fields around, as this kind of struct should not be 272 * initialized like amp_caps are. 273 */ 274 struct amp_state 275 { 276 /* 277 * overridable fields 278 */ 279 280 /* 281 * non overridable fields, internal use 282 */ 283 hamlib_port_t ampport; /*!< Amplifier port (internal use). */ 284 285 int comm_state; /*!< Comm port state, opened/closed. */ 286 rig_ptr_t priv; /*!< Pointer to private amplifier state data. */ 287 rig_ptr_t obj; /*!< Internal use by hamlib++ for event handling. */ 288 289 setting_t has_get_level; /*!< List of get levels. */ 290 291 gran_t level_gran[RIG_SETTING_MAX]; /*!< Level granularity. */ 292 gran_t parm_gran[RIG_SETTING_MAX]; /*!< Parameter granularity. */ 293 }; 294 295 296 /** 297 * \brief Master amplifier structure. 298 * 299 * \struct amp 300 * 301 * Master amplifier data structure acting as the #AMP handle for the 302 * controlled amplifier. A pointer to this structure is returned by the 303 * amp_init() API function and is passed as a parameter to every amplifier 304 * specific API call. 305 * 306 * \sa amp_init(), amp_caps, amp_state 307 */ 308 struct amp 309 { 310 struct amp_caps *caps; /*!< Amplifier caps. */ 311 struct amp_state state; /*!< Amplifier state. */ 312 }; 313 314 315 //! @cond Doxygen_Suppress 316 /* --------------- API function prototypes -----------------*/ 317 318 extern HAMLIB_EXPORT(AMP *) 319 amp_init HAMLIB_PARAMS((amp_model_t amp_model)); 320 321 extern HAMLIB_EXPORT(int) 322 amp_open HAMLIB_PARAMS((AMP *amp)); 323 324 extern HAMLIB_EXPORT(int) 325 amp_close HAMLIB_PARAMS((AMP *amp)); 326 327 extern HAMLIB_EXPORT(int) 328 amp_cleanup HAMLIB_PARAMS((AMP *amp)); 329 330 extern HAMLIB_EXPORT(int) 331 amp_set_conf HAMLIB_PARAMS((AMP *amp, 332 token_t token, 333 const char *val)); 334 extern HAMLIB_EXPORT(int) 335 amp_get_conf HAMLIB_PARAMS((AMP *amp, 336 token_t token, 337 char *val)); 338 extern HAMLIB_EXPORT(int) 339 amp_set_powerstat HAMLIB_PARAMS((AMP *amp, 340 powerstat_t status)); 341 extern HAMLIB_EXPORT(int) 342 amp_get_powerstat HAMLIB_PARAMS((AMP *amp, 343 powerstat_t *status)); 344 345 346 /* 347 * General API commands, from most primitive to least.. ) 348 * List Set/Get functions pairs 349 */ 350 extern HAMLIB_EXPORT(int) 351 amp_get_freq HAMLIB_PARAMS((AMP *amp, 352 freq_t *freq)); 353 extern HAMLIB_EXPORT(int) 354 amp_set_freq HAMLIB_PARAMS((AMP *amp, 355 freq_t freq)); 356 357 extern HAMLIB_EXPORT(int) 358 amp_reset HAMLIB_PARAMS((AMP *amp, 359 amp_reset_t reset)); 360 361 extern HAMLIB_EXPORT(const char *) 362 amp_get_info HAMLIB_PARAMS((AMP *amp)); 363 364 extern HAMLIB_EXPORT(int) 365 amp_get_level HAMLIB_PARAMS((AMP *amp, setting_t level, value_t *val)); 366 367 extern HAMLIB_EXPORT(int) 368 amp_register HAMLIB_PARAMS((const struct amp_caps *caps)); 369 370 extern HAMLIB_EXPORT(int) 371 amp_unregister HAMLIB_PARAMS((amp_model_t amp_model)); 372 373 extern HAMLIB_EXPORT(int) 374 amp_list_foreach HAMLIB_PARAMS((int (*cfunc)(const struct amp_caps *, 375 rig_ptr_t), 376 rig_ptr_t data)); 377 378 extern HAMLIB_EXPORT(int) 379 amp_load_backend HAMLIB_PARAMS((const char *be_name)); 380 381 extern HAMLIB_EXPORT(int) 382 amp_check_backend HAMLIB_PARAMS((amp_model_t amp_model)); 383 384 extern HAMLIB_EXPORT(int) 385 amp_load_all_backends HAMLIB_PARAMS((void)); 386 387 extern HAMLIB_EXPORT(amp_model_t) 388 amp_probe_all HAMLIB_PARAMS((hamlib_port_t *p)); 389 390 extern HAMLIB_EXPORT(int) 391 amp_token_foreach HAMLIB_PARAMS((AMP *amp, 392 int (*cfunc)(const struct confparams *, 393 rig_ptr_t), 394 rig_ptr_t data)); 395 396 extern HAMLIB_EXPORT(const struct confparams *) 397 amp_confparam_lookup HAMLIB_PARAMS((AMP *amp, 398 const char *name)); 399 400 extern HAMLIB_EXPORT(token_t) 401 amp_token_lookup HAMLIB_PARAMS((AMP *amp, 402 const char *name)); 403 404 extern HAMLIB_EXPORT(const struct amp_caps *) 405 amp_get_caps HAMLIB_PARAMS((amp_model_t amp_model)); 406 407 extern HAMLIB_EXPORT(setting_t) 408 amp_has_get_level HAMLIB_PARAMS((AMP *amp, 409 setting_t level)); 410 411 extern HAMLIB_EXPORT(const struct confparams *) 412 amp_ext_lookup HAMLIB_PARAMS((AMP *amp, 413 const char *name)); 414 415 extern HAMLIB_EXPORT(int) 416 amp_get_ext_level HAMLIB_PARAMS((AMP *amp, 417 token_t token, 418 value_t *val)); 419 420 extern HAMLIB_EXPORT(const char *) amp_strlevel(setting_t); 421 422 extern HAMLIB_EXPORT(const struct confparams *) 423 rig_ext_lookup HAMLIB_PARAMS((RIG *rig, 424 const char *name)); 425 426 extern HAMLIB_EXPORT(setting_t) amp_parse_level(const char *s); 427 extern HAMLIB_EXPORT(const char *) amp_strlevel(setting_t); 428 429 //! @endcond 430 431 432 /** 433 * \brief Convenience macro for generating debugging messages. 434 * 435 * \def amp_debug 436 * 437 * This is an alias of the rig_debug() function call and is used in the same 438 * manner. 439 */ 440 #define amp_debug rig_debug 441 442 __END_DECLS 443 444 #endif /* _AMPLIFIER_H */ 445 446 /** @} */ 447