| Name | iu2frl-civ JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | A small library to communicate with ICOM devices using CI-V protocol |
| upload_time | 2025-07-08 20:12:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
icom
ci-v
transceivers
communication
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# IU2FRL ICOM CI-V Python 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
- IC-821H
## 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")`
> [!TIP]
> Usage of named arguments (like `radio_address="0x94"`) over positional arguments is **highly recommended** as it provides better support for future releases or library code reviews
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()`
### 5. Check the command output
Some commands have an expected value to be returned (like the `device.read_operating_frequency()`), most returns a boolean value, while other returns nothing (`void`). If the device does not support a command (or it was not yet implemented), or if some error occurred, an exception is thrown:
- `NotImplementedError`: the current device does not implement this feature yet
- `CivCommandException`: something went wrong in the data exchange between the transceiver and the library (probably due to device misconfiguration, faulty cables, etc)
- `CivTimeoutException`: the communication timed out (something wrong with wiring or connection parameters like port or baudrate)
### 6. Debugging
If some commands are not working as expected, the following code can be used to enable debugging:
```python
import logging
logger = logging.getLogger("iu2frl-civ")
logger.setLevel(logging.DEBUG)
```
## Sample code
> [!IMPORTANT]
> Do not rename the `tests` folder or the `fake_generic.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.
- `ic7300_clock.py`: A simple script to set the clock of the IC-7300 transceiver by syncing to the PC.
- `ic706_mkii.py`: A simple test script that demonstrates how to use the library to communicate with the IC-706 MKII transceiver.
- `fake_generic.py`: A simple test script that fakes a connection to transceiver, used to validate builds.
## Developer info
Any help is welcome to either add more devices or improve existing ones, please see the developers section, accessible via [relative link](./CONTRIBUTING.md) or [GitHub Link](https://github.com/iu2frl/iu2frl-civ/blob/main/CONTRIBUTING.md)
## Device-specific documentation
<details>
<summary>IC-821H</summary>
### General information
- The device seems not to support the `set_operating_frequency` method, so you should use `send_operating_frequency` instead.
- The device seems not to reply to CI-V commands (or maybe my unit is defective?), so the library does not acknowledge any command.
- The device is quite slow in responding to commands, so you should use a longer timeout (default is 1 second).
### Programming a memory channel
To program a memory channel, you can use the `set_memory_mode` method. For example, to set 145.600 FM to channel 79:
```python
print("- Writing 145.600 MHz to memory 79")
radio.set_memory_mode(79)
time.sleep(1)
radio.send_operating_frequency(145600000)
time.sleep(1)
radio.set_operating_mode(OperatingMode.FM)
time.sleep(1)
radio.memory_write()
time.sleep(1)
```
### Scan modes
To scan through memory channels, you first set the channel mode, then you toggle the scan mode:
```python
print("- Setting memory mode")
radio.set_memory_mode(i + 1)
time.sleep(1)
print("- Starting scan")
radio.start_scan()
time.sleep(10)
print("- Stopping scan")
radio.stop_scan()
```
To scan trough frequencyes, first set the frequency mode, then toggle the scan mode:
```python
print("- Setting VFO A")
radio.set_vfo_mode(VFOOperation.SELECT_VFO_A)
time.sleep(1)
print("- Starting scan")
radio.start_scan()
time.sleep(10)
print("- Stopping scan")
radio.stop_scan()
```
</details>
## Project info
### Original project
This project was forked and then improved from: [siyka-au/pycom](https://github.com/siyka-au/pycom)
### Contributors
- [IU2FRL](https://github.com/iu2frl) as owner of the library and the initial implementation for IC-7300
- [IU1LCU](https://www.qrz.com/db/IU1LCU) for extensive testing on the IC-7300
- [ch3p4ll3](https://github.com/ch3p4ll3) for implementing the `DeviceFactory` code and testing on the IC-706 MKII
Raw data
{
"_id": null,
"home_page": null,
"name": "iu2frl-civ",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "icom, ci-v, transceivers, communication",
"author": null,
"author_email": "Luca Bennati <lucabennati1996@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/15/de/ed7b53fffae488a51eb46734e4c4dc9dde058767bbb0ec60f0f88575ab2b/iu2frl_civ-0.3.0.tar.gz",
"platform": null,
"description": "# IU2FRL ICOM CI-V Python Library\n\nPython library for communicating with iCOM radios using CI-V.\n\n## Compatible devices\n\nTheorically speaking, all ICOM devices implementing the CI-V protocol should be compatible, in particular, the following devices were tested:\n\n- IC-7300 (fw: 1.42)\n- IC-706 MKII\n- IC-821H\n\n## Usage\n\n### 1. Installing dependencies\n\n- Install the package using `pip install iu2frl-civ`\n\n### 2. Importing the module\n\n- Import the module using `from iu2frl_civ.device_factory import DeviceFactory`\n\n### 3. Creating the device object\n\n- Initialize the target device using `radio = DeviceFactory.get_repository(radio_address=\"0x94\", device_type=DeviceType.Generic, port=\"COM10\")`\n\n> [!TIP]\n> Usage of named arguments (like `radio_address=\"0x94\"`) over positional arguments is **highly recommended** as it provides better support for future releases or library code reviews\n\nWhere:\n\n- `device_type = DeviceType.Generic` is the type of device you want to control\n- `radio_address = 0x94` is the transceiver address\n\nThen, additional arguments can be passed:\n\n- `port = \"/dev/ttyUSB0\"`: communication port of the transceiver\n- `baudrate: int = 19200`: baudrate of the device\n- `debug = False`: useful to troubleshoot communication issues\n- `controller_address = \"0xE0\"`: address of the controller (this library)\n- `timeout = 1`: serial port communication timeout in seconds\n- `attempts = 3`: how many attempts to perform in case of timeout or errors\n- `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)\n\n### 4. Use the radio object\n\nOnce the device object is created, any supported method can be used, for example:\n\n- Power on the transceiver: `device.power_on()`\n- Get the current frequency: `device.read_operating_frequency()`\n\n### 5. Check the command output\n\nSome commands have an expected value to be returned (like the `device.read_operating_frequency()`), most returns a boolean value, while other returns nothing (`void`). If the device does not support a command (or it was not yet implemented), or if some error occurred, an exception is thrown:\n\n- `NotImplementedError`: the current device does not implement this feature yet\n- `CivCommandException`: something went wrong in the data exchange between the transceiver and the library (probably due to device misconfiguration, faulty cables, etc)\n- `CivTimeoutException`: the communication timed out (something wrong with wiring or connection parameters like port or baudrate)\n\n### 6. Debugging\n\nIf some commands are not working as expected, the following code can be used to enable debugging:\n\n```python\nimport logging\n\nlogger = logging.getLogger(\"iu2frl-civ\")\nlogger.setLevel(logging.DEBUG)\n```\n\n## Sample code\n\n> [!IMPORTANT]\n> Do not rename the `tests` folder or the `fake_generic.py` file, as those are used for testing the library.\n\nSome sample commands are available in the `tests` folder.\n\n- `ic7300.py`: A simple test script that demonstrates how to use the library to communicate with the IC-7300 transceiver.\n- `ic7300_clock.py`: A simple script to set the clock of the IC-7300 transceiver by syncing to the PC.\n- `ic706_mkii.py`: A simple test script that demonstrates how to use the library to communicate with the IC-706 MKII transceiver.\n- `fake_generic.py`: A simple test script that fakes a connection to transceiver, used to validate builds.\n\n## Developer info\n\nAny help is welcome to either add more devices or improve existing ones, please see the developers section, accessible via [relative link](./CONTRIBUTING.md) or [GitHub Link](https://github.com/iu2frl/iu2frl-civ/blob/main/CONTRIBUTING.md)\n\n## Device-specific documentation\n\n<details>\n<summary>IC-821H</summary>\n\n### General information\n\n- The device seems not to support the `set_operating_frequency` method, so you should use `send_operating_frequency` instead.\n- The device seems not to reply to CI-V commands (or maybe my unit is defective?), so the library does not acknowledge any command.\n- The device is quite slow in responding to commands, so you should use a longer timeout (default is 1 second).\n\n### Programming a memory channel\n\nTo program a memory channel, you can use the `set_memory_mode` method. For example, to set 145.600 FM to channel 79:\n\n```python\nprint(\"- Writing 145.600 MHz to memory 79\")\nradio.set_memory_mode(79)\ntime.sleep(1)\nradio.send_operating_frequency(145600000)\ntime.sleep(1)\nradio.set_operating_mode(OperatingMode.FM)\ntime.sleep(1)\nradio.memory_write()\ntime.sleep(1)\n```\n\n### Scan modes\n\nTo scan through memory channels, you first set the channel mode, then you toggle the scan mode:\n\n```python\nprint(\"- Setting memory mode\")\nradio.set_memory_mode(i + 1)\ntime.sleep(1)\nprint(\"- Starting scan\")\nradio.start_scan()\ntime.sleep(10)\nprint(\"- Stopping scan\")\nradio.stop_scan()\n```\n\nTo scan trough frequencyes, first set the frequency mode, then toggle the scan mode:\n\n```python\nprint(\"- Setting VFO A\")\nradio.set_vfo_mode(VFOOperation.SELECT_VFO_A)\ntime.sleep(1)\nprint(\"- Starting scan\")\nradio.start_scan()\ntime.sleep(10)\nprint(\"- Stopping scan\")\nradio.stop_scan()\n```\n\n</details>\n\n## Project info\n\n### Original project\n\nThis project was forked and then improved from: [siyka-au/pycom](https://github.com/siyka-au/pycom)\n\n### Contributors\n\n- [IU2FRL](https://github.com/iu2frl) as owner of the library and the initial implementation for IC-7300\n- [IU1LCU](https://www.qrz.com/db/IU1LCU) for extensive testing on the IC-7300\n- [ch3p4ll3](https://github.com/ch3p4ll3) for implementing the `DeviceFactory` code and testing on the IC-706 MKII\n",
"bugtrack_url": null,
"license": null,
"summary": "A small library to communicate with ICOM devices using CI-V protocol",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/iu2frl/iu2frl_civ",
"Issues": "https://github.com/iu2frl/iu2frl_civ/issues",
"Source": "https://github.com/iu2frl/iu2frl_civ"
},
"split_keywords": [
"icom",
" ci-v",
" transceivers",
" communication"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eaf338517a3e53fb603769fc26d96adc70014038d0037e5e96e0a66c08ec608f",
"md5": "3eaf8340b52bdc2a0e5eab4db6f6ac7e",
"sha256": "4550534a3d0c06b8e6dee49c59c7140cc63a71234c6c5c2c39dd7ef97077e217"
},
"downloads": -1,
"filename": "iu2frl_civ-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3eaf8340b52bdc2a0e5eab4db6f6ac7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47601,
"upload_time": "2025-07-08T20:12:11",
"upload_time_iso_8601": "2025-07-08T20:12:11.898734Z",
"url": "https://files.pythonhosted.org/packages/ea/f3/38517a3e53fb603769fc26d96adc70014038d0037e5e96e0a66c08ec608f/iu2frl_civ-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15deed7b53fffae488a51eb46734e4c4dc9dde058767bbb0ec60f0f88575ab2b",
"md5": "15a42364e128272257c49d1576f87c2c",
"sha256": "2dd80d2423c8b5408fda8eadf743018f20a68dc6bcfa5ea58c5b13491eca9b1d"
},
"downloads": -1,
"filename": "iu2frl_civ-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "15a42364e128272257c49d1576f87c2c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39629,
"upload_time": "2025-07-08T20:12:13",
"upload_time_iso_8601": "2025-07-08T20:12:13.317226Z",
"url": "https://files.pythonhosted.org/packages/15/de/ed7b53fffae488a51eb46734e4c4dc9dde058767bbb0ec60f0f88575ab2b/iu2frl_civ-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 20:12:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iu2frl",
"github_project": "iu2frl_civ",
"github_not_found": true,
"lcname": "iu2frl-civ"
}
