iu2frl-civ 0.1.3

A small library to communicate with ICOM devices using CI-V protocol

IU2FRL ICOM CI-V Library

Python library for communicating with iCOM radios using CI-V.

Compatible devices

Theorically speaking, all ICOM devices implementing the CI-V protocol should be compatible, in particular, the following devices were tested:

• IC-7300 (fw: 1.42)
• IC-706 MKII

Usage

1. Installing dependencies

• Install the package using pip install iu2frl-civ

2. Importing the module

• Import the module using from iu2frl_civ.device_factory import DeviceFactory

3. Creating the device object

• Initialize the target device using radio = DeviceFactory.get_repository(radio_address="0x94", device_type=DeviceType.Generic, port="COM10", debug=True)

Where:

• device_type = DeviceType.Generic is the type of device you want to control
• radio_address = 0x94 is the transceiver address

Then, additional arguments can be passed:

• port = "/dev/ttyUSB0": communication port of the transceiver
• baudrate: int = 19200: baudrate of the device
• debug = False: useful to troubleshoot communication issues
• controller_address = "0xE0": address of the controller (this library)
• timeout = 1: serial port communication timeout in seconds
• attempts = 3: how many attempts to perform in case of timeout or errors
• fake = False: if set to True, the library will use a fake connection to the transceiver (serial commands will be printed to the console and not sent to any port)

4. Use the radio object

Once the device object is created, any supported method can be used, for example:

• Power on the transceiver: device.power_on()
• Get the current frequency: device.read_operating_frequency()

Developer info

Device Types

The DeviceType enum is a custom implementation for categorizing different types of transceivers.

It currently includes:

• Generic: A generic device type (built using the IC-7300 CI-V manual).
• IC_706_MK2: Represents the IC-706 MKII transceiver model.
• IC_7300: Represents the IC-7300 transceiver model.

Adding a new device to the library

This process involves three main steps:

• Update DeviceType Enum: A new entry will be added to the DeviceType enum to reflect the newly added device.
• Create a Device class: You will define a new class that will serve as your device plugin.
• Update package info: Add an entry in the pyproject.toml to register the plugin.
• Create a test script: Create a new test script in the tests folder to test the new device.
• Manual build procedure: Before sending the merge request, please try to build the package locally and make sure everything works.

1. Add Device to the DeviceType Enum

To include your new device in the DeviceType enum, update the iu2frl_civ.enums file by adding a new member for the new device.

For example:

from enum import Enum


class DeviceType(Enum):
    """Custom implementation for different transceiver"""
    Generic = 0
    IC_706_MK2 = 1
    NewDevice = 99  # New device added here
 
 ...

2. Create a new Device class

A plugin is a class that represents a specific device. To create a new plugin:

• Create a new file in the iu2frl_civ/devices/ directory.
• Define a new class that extends iu2frl_civ.device_base for your device and add the required attributes (device_type, device_class)

for example:

# iu2frl_civ/devices/new_device.py

from ..device_base import DeviceBase  # Import the base class

class NewDevice(DeviceBase):
    """Representation of the new device."""
    
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.utils = Utils(
            self._ser,
            self.transceiver_address,
            self.controller_address,
            self._read_attempts
        )
    
    def read_operating_frequency(self) -> int:
        # Implement device-specific logic here
        pass


# Required attributes for plugin discovery
device_type = DeviceType.NewDevice # As specified in the DeviceType enum
device_class = NewDevice # Name of the class defined above

Note: If your device does not support certain functions (e.g., power_on(), power_off(), etc.), you do not need to implement them. The library will automatically raise a NotImplementedError when any unsupported method is called.

3. Update pyproject.toml

[!IMPORTANT] Do not edit the line with version = "v0.0.0" as this is automatically set by GitHub when building the new release

Next, you need to register your new device in the pyproject.toml file so that it can be discovered and loaded as a plugin.

Open your pyproject.toml file and add a new entry under the [project.entry-points] section to register your plugin.

for example:

[project.entry-points."iu2frl_civ.devices"]
generic = "iu2frl_civ.devices.generic"
ic7300 = "iu2frl_civ.devices.ic7300"
ic706_mkii = "iu2frl_civ.devices.ic706_mkii"
new_device = "iu2frl_civ.devices.new_device"  # New entry for the plugin

4. Create a test script

To test the new device, create a new test script in the tests folder. This script should import the new device and test its functionality. Testing should be done without building the package.

• You can copy the fake.py script as a template.
• If you have a real device, you can test the new device by running the test script and checking the output.
  • Make sure the Fake parameter is set to False in the DeviceFactory.get_repository method.
• Test the new device by running the test script and checking the output (without building the package yet).
  • Make sure to uninstall any version of the library that was previously installed using pip uninstall iu2frl-civ

5. Manual build procedure

Before sending the merge request, please try to build the package locally and make sure everything works

1. Move to the root directory of the project (where the pyproject.toml file is located)
2. Install the build tools: python -m pip install --upgrade build
3. Build the wheel package: python -m build
4. Install the package that was just built: pip install ./dist/iu2frl_civ-0.0.0.tar.gz
5. Test the package using the test code in the tests/fake.py file (the script will now use the newly built package)
6. Test the package using the code in the test file you just created

Sample code

[!IMPORTANT] Do not rename the tests folder or the fake.py file, as those are used for testing the library.

Some sample commands are available in the tests folder.

• ic7300.py: A simple test script that demonstrates how to use the library to communicate with the IC-7300 transceiver.
• ic706_mkii.py: A simple test script that demonstrates how to use the library to communicate with the IC-706 MKII transceiver.
• fake.py: A simple test script that fakes a connection to transceiver, used to validate builds.

Project info

Original project

This project was forked and then improved from: siyka-au/pycom

Contributors

• IU2FRL as owner of the library and the initial implementation for IC-7300
• IU1LCU for extensive testing on the IC-7300
• ch3p4ll3 for implementing the DeviceFactory code and testing on the IC-706 MKII