Project

General

Profile

DevelopersAdd a Radio » History » Version 17

Dan Smith, 07/29/2023 08:17 AM

1 9 Dan Smith
# How to add a new radio driver
2 1 Tom Hayward
3
You've got a radio that's not in Chirp, a little bit of software development experience, and you want to add that radio to Chirp. Here's what you'll need:
4
5 9 Dan Smith
* a subscription to the [chirp_devel mailing list](http://intrepid.danplanet.com/mailman/listinfo/chirp_devel)
6
* a Python development environment
7 1 Tom Hayward
* radio
8
* programming cable
9
10 9 Dan Smith
## Setting up the development environment
11 1 Tom Hayward
12
If you want to develop in another operating system, you're on your own. This guide isn't going to cover it. Here's a guide for Windows: [[DevelopersWin32Environment]].
13
14 9 Dan Smith
## Look over some existing code
15 1 Tom Hayward
16
Read source:chirp/drivers/template.py. The whole thing.
17
18
This serves as a starting point for understanding the structure of a driver for a radio that operates in "clone mode", which is by far the most common type of radio and CHIRP driver. If your radio will operate in "live mode", and especially if your radio uses the CAT protocol, you should probably start by reading source:chirp/drivers/kenwood_live.py.
19
20 17 Dan Smith
## Clone vs. Live Mode
21
22
Most radios seem to have a mode for which memory can be read or written as a large block, and their drivers reflect that. These are called "clone mode" drivers and this approach should be taken if the radio supports it. A few radios can only be accessed on what is effectively memory-by-memory reads/writes. These radios will almost surely need to be written as “live mode”. An example driver is at `chirp/chirp/drivers/kenwood_live.py`. Several other Kenwood drivers inherit from that one (at least `ts480.py`, `tmd710.py`, `ts2000.py`.) These drivers do not download a full copy of the radio all at once, but are expected to fetch memories from the radio at the time `get_memory()` is called from the GUI.
23
24 9 Dan Smith
## Write the download/upload routines
25 1 Tom Hayward
26 9 Dan Smith
### Sniffing the protocol used by existing software
27 1 Tom Hayward
28 9 Dan Smith
If you have other programming software for your radio, such as the software from the manufacturer, you can sniff the serial programming protocol with [Portmon](http://technet.microsoft.com/en-us/sysinternals/bb896644.aspx). Typically, radio programming software is written for Windows, and Portmon is a Windows utility.
29 1 Tom Hayward
30 9 Dan Smith
For recent versions of Windows, you might try sniffing USB with [USBPcap](http://desowin.org/usbpcap/). The captured data is analysed with any recent version of [Wireshark](http://www.wireshark.org).
31 1 Tom Hayward
32
Start with a read.
33 4 Aaron P
34 9 Dan Smith
1. Click Read in the official software
35
1. Watch the output of Portmon after you click Read
36
1. Look for a line that sets the BAUD RATE. Sometimes there are a few of them.
37
1. Look for a WRITE line with a few data bytes. This is probably the command to tell the radio to start sending data.
38
1. Look for READ lines with lots of data bytes after them. This is probably the memory contents of the radio being downloaded
39
1. You're a smart developer. You should be able to figure out the protocol from here!
40 1 Tom Hayward
41
You can also sniff a many Windows programs by running them in the Wine environment under Linux. Manufacturers' radio programming software is likely to run in this environment. See [[DevelopersUSB Sniffing in Linux]].
42
43
h3. Using existing Chirp code
44
45
If the radio you're developing for doesn't have existing programming software, you won't be able to use the above reverse engineering technique. Most radio manufacturers use a common protocol across most of their radios. Because Chirp supports so many manufacturers, there's a chance an existing radio driver has a download routine that will work with your new radio. This is especially true with Yaesu radios (other than the FT-4/FT-65 family), which don't really even have a protocol. They just dump their memory. All you need to figure out is the baud rate and the memory size (and baud rate is usually 9600).
46
47 5 Daniel Clemmensen
Choose a radio driver that you think might be similar. If you were going to add the VX9, you might start with the VX8 driver:
48 1 Tom Hayward
49 9 Dan Smith
```
50
$ cd chirp/chirp
51
$ sed s/VX8/VX9/g vx8.py > vx9.py
52
```
53 1 Tom Hayward
54 9 Dan Smith
Increase the `_memsize` variable significantly. The goal is to read more data than the radio sends.
55 1 Tom Hayward
56
Launch Chirp and start a download with your new radio driver. Did it work, sort of? Save the .img.
57
58 9 Dan Smith
Now we're going to determine the `_memsize`. Open the .img in a hex editor:
59 1 Tom Hayward
60 9 Dan Smith
```
61
$ hexdump -C VX9_oversize.img | less
62
```
63 1 Tom Hayward
64 9 Dan Smith
Look towards the end of the file for the offset where the data becomes all zeros. This is your `_memsize`. The radio has stopped sending data, but Chirp was still "reading". Change `_memsize` in your driver so that Chirp reads the same number of bytes the radio is sending.
65 1 Tom Hayward
66
h2. Map the memory blob
67
68
To map the memory layout, you're going to make a small change on the radio, do a download, then look for differences. Do this over and over until you have the whole memory layout mapped.
69
70
Here's a little helper script I use for the comparisons:
71
72 9 Dan Smith
`hexdiff.sh:`
73
74
```
75 1 Tom Hayward
#!/bin/sh
76
77
A=`mktemp`
78
B=`mktemp`
79
80
hexdump -C $1 > $A
81
hexdump -C $2 > $B
82
diff $A $B | less
83
rm $A $B
84 9 Dan Smith
```
85 1 Tom Hayward
86 9 Dan Smith
1. Find the first channel
87
1. Find the second channel
88
1. The offset between the two is your memory channel struct size
89
1. Find the last channel. Hopefully its offset is struct size * advertised number of channels away from the first channel!
90 1 Tom Hayward
91
You'll probably start off with something like this:
92 9 Dan Smith
```
93 1 Tom Hayward
MEM_FORMAT = """
94
#seekto 0xb00;
95
struct {
96
  u32 freq;
97
  u8 unknown1;
98
  u8 unknown2;
99
  u8 unknown3;
100
  char name[8];
101
} memory[200];
102
"""
103 9 Dan Smith
```
104 1 Tom Hayward
105 9 Dan Smith
`0xb00` is the location of the first memory channel.
106
`200` is the number of channels the radio supports.
107
`unknown1`, `unknown2`, and `unknown3` are for memory-specific settings (e.g., tone) that you haven't sussed out yet.
108 1 Tom Hayward
109 10 Dan Smith
## Write `get_memory()`
110 1 Tom Hayward
111 11 Dan Smith
This is called to get your driver to populate the CHIRP memory model with the data for one radio memory. On startup, it’s called once for each memory register you’ve delimited for your radio and once for each special memory. Later it will be called as needed.
112
113
* `get_memory()` returns a populated CHIRP memory object that the driver creates as a new instance of the chirp_common.Memory structure. You’ll want to become familiar with the fields in the Memory structure (presently specified in the source tree in the source file `chirp/chirp_common.py`).
114
  
115
* The number of memories is specified in `chirp_common.RadioFeatures.memory_bounds`, which is a pair of numbers (first memory number, last memory number.) `get_memory()` will be called with an integer parameter for regular memories with a value up to the last memory number.
116
117
* Special memories are radio-specific channels that can hold special meaning in the radio (such as scan limits, home/call channel, skip channels, etc.) They are specified in your driver as members of the list that you set at `chirp_common.RadioFeatures.valid_special_chans`. `get_memory()` will be called with a string containing the name of the special channel, and you must set the `Memory.number` field of the resulting memory object to an index that is greater than the last memory register number and different than other special memories without holes in the sequence. Subsequent calls to `get_memory()` may receive either the index or the name.
118
119
Do read the example driver at `chirp/chirp/drivers/template.py`. There is a commented stub version of this routine in `chirp/chirp.common.py`. Your driver is expected to override it.
120
121 9 Dan Smith
## Write `set_memory()`
122 1 Tom Hayward
123 12 Dan Smith
This is called whenever CHIRP wants your driver to set a memory channel according to the fields described in the specific `chirp_common.Memory` parameter. The driver will presumably need to determine the specific place in the radio's memory based upon the value of `memory.number` (e.g. integer less than or greater than last memory number.) The driver should not change the memory structure.
124
125
There is no return value from `set_memory()`.
126
127
Do read the example driver at `chirp/chirp/drivers/template.py`. There is a commented stub version of this routine in `chirp/chirp.common.py`. Your driver is expected to overload it.
128
129 13 Dan Smith
## Per-memory extra settings
130 12 Dan Smith
131 13 Dan Smith
CHIRP can (optionally) manage and display other settings for each memory. These are stored in `chirp_common.Memory.extra`, and are handled by your driver during the `get_memory()` and `set_memory()` by setting or honoring the `extra` field, which should be a `settings.RadioSettingGroup` object.
132 12 Dan Smith
133 16 Dan Smith
## Register your driver
134
135
CHIRP has a “directory” structure of all the radios it should know about. Your driver will have one or more `@directory.register` statements, wherein a class is defined for each radio you’re working on. They can inherit from each other (even other models and vendors) once the classes are read by CHIRP. The directory is sorted by text (vendor, model) pairs.
136
137
## Write get_settings()
138
139
Your driver class will have definitions (and some redefinitions) for your radio. It will also implement a function `get_features()` which returns a `chirp_common.RadioFeatures()` object. This contains information about your radio so that CHIRP knows the basic attributes. Any existing driver should have one for you to copy and modify. CHIRP calls this often and from pretty much everywhere, so it must be lightweight. This method should not be querying the radio or even digging deep into memory each time it’s called.
140
141 9 Dan Smith
## Add an image of your radio to the tree
142 1 Tom Hayward
143 9 Dan Smith
Save it to `tests/images/Vendor_Model.img`
144 1 Tom Hayward
145 9 Dan Smith
## Run tests
146 1 Tom Hayward
147 9 Dan Smith
Make sure all the tests pass before you submit:
148
149
```shell
150
$ tox
151
```
152
153 15 Dan Smith
See [[DevelopersPython3Environment]] for more examples of running tests. All the tests must pass before your code can be merged.
154 14 Dan Smith
155 9 Dan Smith
## Submit code to github