8.0 Information for Software developers

Times have marched on since I started this CI-V information pages around 2003. When I started there was no Git, leave alone github. But now we have all these nice things, and CAT control of transceivers has become common. My general recommendation for a developer is: use hamlib. In 2019 hamlib has become a very mature library with a history of more than 10 years. It is used in fldigi, WSJT-X and many other software projects. If you want to write your own software, read on.

8.1 Delphi

To get CI-V to work, you have to control the serial interface of your PC. There are a lot of components (free and others) for Delphi which help you in doing that, look at the usual Delphi Pages (torry, DSP etc.). I personally use TSerial4 by R.Crowther and recommend it, although it's not free. The original link has goine away, maybe you can find something at http://delphi.icm.edu.pl/authors/a0002072.htm. I do not use Delphi anymore.

Serial comms happen with 8 bit, no parity, one stopbit, speed varies from 1200 to 19200 bps. Formerly 1200 bps was the normal speed for CI-V, but with most modern ICOM rigs you can set it to any other speed. As with many things - the faster the better.

Once you have serial comms up and running, you have to wait for incoming bytes. Each telegram of the CI-V protocol is in the same format, it begins with two '$FE' characters (bytes) and ends with one '$FD' byte. So you could just wait for an $FD and then work on the telegram. But there are pitfalls in this approach.

Since the CI-V line is a bus with perhaps several radios connected, collisions can occur (multiple radios sending data at once). In case of an collision a rig sends out the '$FC' character several times. On your serial port you might get a framing or other errors. So you have to check the received telegram for validity.

Here is how I do it (there are other ways, mine isn't probably the best and certainly not the only way to do it, but i found it to work very reliably):
I use a so called 'state machine', this is a routine which gets called each time one byte is received on the serial port. The state machine uses one variable, the state machine 'state'. This variable is used in a 'case' statement and selects the following execution path. Initially this is set to 'WaitPreamble1'.
Once i have received the first $FE i set the state to 'WaitPreamble2'. The next character comes in, the case branches to 'WaitPreamble2'. If this character is again a $FE the state variable is set to 'WaitToAdress', nothing else.
When the next byte is received the case branches to 'WaitToAdress', the byte is validated if it is a possible adress, if yes the state is advanced to 'WaitFromAdress'. If not, the state is set back to start, 'WaitPreamble1', ignoring the rest of the telegram.
This checking for errors on each stage is critical in ensuring that a valid frame (telegram) is received before acting on it.
After going through stages 'WaitPreamble1', 'WaitPreamble2', 'WaitToAdress' and 'WaitFromAdress' I set up a buffer (a record) which will hold the incoming message. In the following stages this buffer is filled (command, subcommand, data etc.) and, once it is complete, handed to a routine which processes the telegram (read out and display frequency information for example).

Perhaps it's best to show some code here:

procedure Readbyte(b: byte);
  case state of
    WaitPreamble1: if b=$FE then state:=WaitPreamble2; //nothing else expected

    WaitPreamble2: if b=$FE
                      then state:=WaitToAdress    //advance state
                      else state:=WaitPreamble2;  //not what i expected, back to start

    WaitToAdress:  if (b=$E0) or (b=$00) //adressed to me ($E0) or to all ($00)
                      then state:=WaitFmAdress   //ok
                      else state:=WaitPreamble1; //not for me, back to square one

    WaitFmAdress:  if b=TheRigIwantToTalkTo //comes from the correct radio?
                      then begin //yes
                           incoming.from:=b; //remember where it came from
                      else state:=WaitPreamble1; //not the radio i expect

    WaitCommand:  if b<$1F //valid command byte?
                     then begin
                     else begin
                          Dispose(incoming); //discard what we started earlier
                          state:=WaitPreamble1; //start over

    WaitFinal: if b=$FD //is telegram complete ?
                  then begin
                       ProcessTelegram(incoming); //will dispose the buffer
                  else begin
                       //no state change here, continue to wait.
                       //you could check for max length or other errors.
        end; //case

The variables 'state' and 'incoming' are declared global in the unit.
One could add more error checking at each stage, e.g. look for framing errors from the serial port in case of a collision, or check if character '$FC' was received at any point. If an error occurs, discard what you received so far and start over.

There are some pitfalls here... e.g. what happens if a new telegram arrives before processing of the old has finished? For that reason I put the received telegram in a queue, the "ProcessTelegram" routine then checks the queue and works on the topmost (oldest) telegram only and finally disposes it. With the queue it can take all the time it wants for processing.
Other problems can arise from this approach, for example race conditions in managing the queue, but this example here is just to show the basic principles.

9.2 Visual Basic

As I don't use VB myself, I am depending on others here.
Wayne was so kind and provide an example, complete for VB6. Many thanks, Wayne! He writes:

3/19/02 by WRS

Another example or R7100 programming.

Contains an Auto-ID routine for automatically determining the Receiver ID
if you have correctly selected the Baud Rate and the Com Port. You however
must save the configuration and exit the program and restart it before the
ID change will take effect.

It should work on any ICOM however I only tested it on the R-75 and the
R-7100. My R-7100 is set as ID 14 Hex 20 Decimal and my R-75 is set as ID
5A Hex and 90 Decimal.

All of the Manual tuning works fine. I am currently developing the scanner
mode capability.
On the intro screen (R7100 in center) just close it with the "X" in the upper
right corner of the form. Be sure to select the baud rate and com port to match
your connection and use the save configuration in the configuration menu. Then
you can use the Auto-ID under the R7100 menu, it will show the detected decimal
ID and then you save the configuration once again. Now exit the program and restart
it. It will read in your configuration and use it.

You may then select Manual Tune to open the manual tuning area. All frequencies
entered are in pairs. In other words if you put in 162.55 or 99.50 or 76.25. You
cannot put in 162.5 or it will give an incorrect tuning.

Take care & Enjoy!


Download the code complete with VB6 sources here. (50KB, ZIPped files).

9.3 Perl

Since some years I have switched to Linux and rarely write software for Windows anymore. My language of choice to start with under Linux is Perl. I really love it, it's a great language.

I have written two modules which facilitate the use of the CI-V commands: icomdefs.pm and icomcivio.pm. Further you have to use a module for controlling the serial port. I use Device::Serialport, see your local CPAN.

9.4 C, C++, Visual C

Артём Пинчук (Artem Pinchuk) shares his C++ code which is hosted on github. Many thanks, Artem!