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.
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