Hampod Project Hamlib

Introduction

Hamlib, short for "Ham Radio Control Libraries," is an open-source project that provides a standardized interface and API (Application Programming Interface) for controlling various amateur radio transceivers. It aims to offer a unified software platform for interacting with different radio models, allowing developers to create applications that can communicate with multiple radios using a consistent interface.

Key features of Hamlib include:

• Cross-platform compatibility: Hamlib supports various operating systems, including Windows, Linux, and macOS, enabling radio control on different platforms.
• Wide device support: It supports a wide range of radio models from different manufacturers, including popular brands such as Yaesu, Icom, Kenwood, and Elecraft.
• Rig control functionality: Hamlib provides features for controlling and configuring various aspects of the transceiver, such as frequency setting, mode selection, power output, filters, and more.
• Remote control capabilities: It allows remote operation of the radio over network connections, enabling users to control their radios from different locations.
• Software development support: Hamlib provides programming language bindings for multiple languages, making it easier for developers to integrate radio control into their applications.

Links

• Hamlib Github Link can be found here.
• Hamlib Documentation can be found here.
• Hamlib Community can be found here.

Hamlib in the Hampod

In order to allow for users to interface with multiple radios, several files had to be implemented with Hamlib functions.

HamlibSetFunctions (.c/.h files)

The HamlibSetFunctions file acts as an adapter for Hamlib by using wrapper functions which then call the Hamlib functions directly. This allows for the ability to swap out Hamlib with another radio interface library without the need to revamp the entire system.

The HamlibSetFunctions file consists of all function that pertain to setting some value on the rig (e.g. Setting the frequency). Each wrapper function follows a similar format:

1. Parse the provided void pointer array.
2. Call the Hamlib set function.
3. Convert the output to a string specified towards the command.
4. Return the string output.

Why was each function structured this way? I felt it allowed for custom modification to the string output if need be.

To add new Hamlib set functionality, simply copy and paste the following template, and then add the new functionality.

char* set_value(void* input) {
    RIG* rig = ((void**)input)[0]; // These will most of the time be the same. 
    vfo_t vfo = *((vfo_t*)((void**)input)[1]);
    <VALUE TYPE HERE> value = *((<ADD CAST TYPE HERE SIMILAR TO VFO>)((void**)input)[2]);
    
    char* output = malloc(100); 
    int retcode = <HAMLIB SET FUNCTION HERE>
    if (retcode == RIG_OK) {
        snprintf(output, 100, "<CHANGE PRINT AS YOU LIKE> %.3f\n", value);
    } else {
        printf("<CHANGE PRINT AS YOU LIKE>: error = %s\n", rigerror(retcode));
        snprintf(output, 100, "-1\n");
    }
    return output; 
}

Currently Implemented Set Functions

The following is a set of Hamlib set functions that exist within the HamlibSetFunctions file (NOTE: Some of these functions might not work due to either Hamlib not supporting a rig for the specified function or the lack of testing on some).

• set_frequency
• set_mode
• set_vfo
• set_ptt
• set_rit_offset
• set_xit_offset
• set_tuning_step
• set_CTCSS_sub_audible_tone
• set_current_encoding_digitally_coded_squelch_code
• set_current_CTCSS_sub_audible_squelch_tone
• set_current_continuous_tone_controlled_squelch_code
• set_level (Any of the RIG_LEVEL features in Hamlib)
• set_func (Any of the RIG_FUNC features in Hamlib)

HamlibGetFunctions (.c/.h files)

The HamlibGetFunctions file acts as an adapter for Hamlib by using wrapper functions which then call the Hamlib functions directly. This allows for the ability to swap out Hamlib with another radio interface library without the need to revamp the entire system.

The HamlibGetFunctions file consists of all function that pertain to setting some value on the rig (e.g. Setting the frequency). Each wrapper function follows a similar format:

1. Parse the provided void pointer array.
2. Call the Hamlib get function.
3. Convert the output to a string specified towards the command.
4. Return the string output.

Why was each function structured this way? I felt it allowed for custom modification to the string output if need be.

To add new Hamlib get functionality, simply copy and paste the following template, and then add the new functionality.

char* get_value(void* input) {
    RIG* rig = ((void**)input)[0]; // These will most of the time be the same. 
    vfo_t vfo = *((vfo_t*)((void**)input)[1]);

    <VALUE TYPE HERE> value;     
    char* output = malloc(100); 
    int retcode = <HAMLIB GET FUNCTION HERE>
    if (retcode == RIG_OK) {
        snprintf(output, 100, "<CHANGE PRINT AS YOU LIKE> %.3f\n", value);
    } else {
        printf("<CHANGE PRINT AS YOU LIKE>: error = %s\n", rigerror(retcode));
        snprintf(output, 100, "-1\n");
    }
    return output; 
}

Currently Implemented Get Functions

The following is a set of Hamlib get functions that exist within the HamlibGetFunctions file (NOTE: Some of these functions might not work due to either Hamlib not supporting a rig for the specified function or the lack of testing on some).

• get_frequency
• get_mode
• get_vfo
• get_ptt
• get_rit_offset
• get_xit_offset
• get_tuning_step
• get_CTCSS_sub_audible_tone
• get_current_encoding_digitally_coded_squelch_code
• get_current_CTCSS_sub_audible_squelch_tone
• get_current_continuous_tone_controlled_squelch_code
• get_level (Any of the RIG_LEVEL features in Hamlib)
• get_func (Any of the RIG_FUNC features in Hamlib)

Modes (.c/.h files)

A majority of the modes on the Hampod call functions either from Hamlib or external functions (that act as adapters) that then call Hamlib. Specifically, Normal Mode and Monitoring Mode call functions from the HamlibSetFunctions and HamlibGetFunctions files (Frequency Mode calls Hamlib directly since we did not have time to convert it over; however it should be a simple change).

Normal Mode

For more information about the Normal Mode specifically, refer here.

Frequency Mode

For more information about the Frequency Mode specifically, refer here.

Monitoring Mode

For more information about the Monitoring Mode specifically, refer here.

Radio (.c/.h)

The Radio file is the object that stores any important information about the Radio connected. Specifically, the "rig_model_t" and "port" variables are what require Hamlib to work properly.

When initialized with these values, the Radio object can call:

• "rig_init" to initialize the rig in Hamlib.
• "rig_set_conf" from Hamlib to choose the port.
• "rig_open" to open the connection between the user's radio and the Hampod.

When the connection is closed, the Radio object uses the function "freeRadio" which calls the Hamlib functions:

• "rig_close" to close the connection between the user's radio and the Hampod.
• "rig_cleanup" to clear the memory of the previously connected rig.

Startup (.c/.h)

The Startup process also uses Hamlib to pull supported rigs. Using the function “rig_list_foreach(callback, &rig)”, every “rig” supported by Hamlib is called on the function “callback”. Then the rig object, specifically the information like id and model, can be pulled and appended to its respective company text file. It's such a useful function to allow for the Hampod's life to be extended.

For more information about the Startup process specifically, refer here

Acknowledgements

I special thanks to Michael Black for continuing a great open-source library to work with as well as providing help and feedback on the forums.