6.1  piWebCAT - Icom CI-V configuration


piWebCAT's control actions are NOT read-modify-write (unlike my EncoderCAT project)
The controls are synchronised to the radio's settings at startup, on band change and by the reload button.

This uses the read  and  answer configurations to request the data and interpret the answer.

Subsequent button or slider action commands use set configurations with the new position of a slider,
or from known buttons states.      ie: only the set commands are used.... there is no feedback.

(eg: for toggled buttons, piWebCAT uses the button's remembered on or off state to determine the new state.)


Icom CI-V uses CAT byte sequences that are specified in hexadecimal:

  • Hexadecimal command codes, eg:  1A hex
  • Decimal data values represented in Binary Coded Decimal format  (BCD)


Hexadecimal bytes are represented in this document with the prefix 0x. ( as used C and PHP languages)

    eg: 0x2A  is hexadecimal 2A  = 2 x16 + 10 =  decimal 42

 

BCD format represents two decimal digits as a single hexadecimal byte.

    eg:  decimal 37  is  0x37 ... easy to read   (but on hex to dec conversion = 3 x16 +7 = 55 decimal)


piWebCAT software does the decimal to BCD conversion for you.
This allows you to enter command 050014 as such in decimal.

The value is sent to the server as decimal 050014.
The server then transmits this as three bytes:  0x05  0x00  and 0x14.


Icom's command system is complicated by what would appear to be historical / evolutionary features.

The range of formats includes:

  • single hex command byte
  • hex command byte + hex sub-command
  • hex command byte + hex sub-command byte + bcd data bytes.  (read only - but read/write in later rigs)
  • hex command byte + two bcd data byes  ( read/write). The bcd bytes referred to as sub-command
  • hex command byte + three bcd data bytes. ( read/write). The bcd bytes referred to as sub-command


piWebCAT provides a CI-V user configuration system that supports these formats.


piWebCAT CIV tables

Three table are involved in CIV communication:

  • catcodesciv   Generating server to radio commands from buttons table request from the client.
                       Decoding button state data from the radios at start up and on VFO or band change.

                   Also has the CIV control information for frequency read and write.

  • slidersciv            One table providing client AND server data fields.
                       (Unlike buttonsciv which controls only client functions and uses catcodesciv for server. functions)
  • meterciv            Controls client and server meter reading functions.


These three tables control the CIV communications using fields :
               rigaddr, rpiaddr, cmdtype, datadigits, com, subcom and subcom4or6.
 


How this works is described below rather in the individual table descriptions.


CI-V control fields


I use the abbreviation com for command and subcom for sub command.


Hexadecimal bytes are shown as 0xFE etc.  BCD was explained above.


CI-V commands have the form show below.

0xFE | 0xFE | rig addr. byte | control. addr. byte | com byte | subcom  byte(s) | databyte(s) | 0xFD  


The 0xFE bytes are start / security bytes.    0xFD is an obligatory terminating bytes.


In data returned from the radio, rig addess. and controller address are reversed.

 

The cmdtype field in a table defines the type of CI-V command and how the other fields are used.


cmdtype has seven possible values which are described below.


The codes (eg: C_S_DATA) are descriptive.  

eg:  C_S6_DATA has a six digit decimal subcommand > coded into 3 BCD bytes

com is always a hexadecimal byte,  eg 0x1A

subcom is a hexadecimal byte   OR   2 BCD bytes    OR 3 BCD bytes


The seven cmdtype values are:


  • C_S_DATA             Com byte (hex)      Subcom byte (hex)               Data byte(s)
  • C_S6_DATA    Com byte (hex)       3 Subcom bytes (BCD)       Data byte(s)        
  • C_S4_DATA    Com byte (hex)       2 Subcom bytes (BCD)       Data bytes(s)
  • C_S_ONOFF   Com byte (hex)       Subcom byte (hex)          1 or 0 for on/off
  • C_S            Com byte (hex)       Subcom (hex)        
  • C_ONOFF       Com byte (hex)       1 or 0 for on/off        
  • C_DATA         Com byte (hex)        Data byte(s)
  • C_ONLY            Com byte (hex)       no subcom, no data (eg: 0x0A = memory to VFO )


The tables have CIV control fields as follows.  ( cmdtype dictates the use of the other fields.)


  • rigaddr        The address of the radio - usually 0x70  .. but can be changed if multiple radios.
  • rpiaddr        The send address of the piWebCAT RPi   I always use 0xE0
  • cmdtype        as above
  • datadigits        The number of decimal digits.  When configuring a command, look at the data.
                   Example: if data is specified as 0-255 then datadigits = 3
                   Two BCD bytes will be used. eg:  147 is coded as 0x01  0x47.

               (Care needed!! eg: If I set datadigits = 5 here, then 3 bytes are sent - and it fails)

  • com        The hex com, eg 1A
  • subcom        The hex subcom if used -- only for C_S_DATA, C_S_ONOFF and C_S.
  • subcon4or6  Decimal  subcom  - see above   -  for C_S6_DATA and C_S4_DATA