piWebCAT

3.7  piWebCAT  - setup - Important reading

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

The database is named radios.

Database tables

It contains 10 tables:

• buttons, sliders, catcodes and meter are used for ASCII and YAESU5 radios.
• buttonsciv, slidersciv, catcodesciv and meterciv are for Icom CI-V radios.
• buttonshl, slidersshl, catcodeshl and meterhl are used for HAMLIB configurations.
• rigs, settings, timings, lookups, metercal and bands are used by all radios.
• log  stores the station log.

The tables can hold records for multiple radios.

A radio is identified by the rig field. This is a character string that must spelled correctly, otherwise the record
will disappear from piWebCAT's editor.

What not to change!

piWebCAT's configuration system is flexible in that it allows the user to create new control items and to name
their control codes. However, their are certain names / fields which must not be changed.
These are listed below:

• The 91 buttons and 27 sliders have a fixed allocated numeric references: btnno and sliderno
  These are identified on a control page layout on the preceding page.
  They are hard coded in the software.
• code fields are the link between client data and server data, eg: NRSW, VXSW etc
  Many of these could be changed provided that the same name is used in client and server  (see below)
  However, certain code items are used in the software and so must not be changed:
  ie: BAND, MODE, VFO, FREQ,  SWAP, SPLT, ATOB, BTOA, MOX, TXME, MORE, MPAD,
       CWME, MECH, FRUP, FRDN, RPGO, CWRP, PWRF.
• The available values of active, abx, vx, lookup, action, numchar, usecal, meter,
   catcomms, connection, vfobvis, afswap, disable, cmdtype are fixed. (eg: some are just Y / N )
  These are in fact all offered by drop down selectors in piWebCAT's editors ... so you can't go wrong
     - but they have to be typed when you use an external editor such as MySQL Front.

Tables:  buttons, catcodes, sliders, meter
The above are ASCII radios tables.
The following equally applies to CIV tables: bttonsciv, catcodesciv, slidersicv, meterciv)

I give FTdx101D examples.

Much of this discussion relates to the fact that one slider on the client will control two radio
parameters, once in each receiver according to current VFO A/B selection.

(NB: The FTdx101D has two completely separate receiver modules and so most receiver control
 setting are set separately for each receiver. This is not so in all 'dual VFO' radios.)  

sliders

The sliders table holds both client and server data.
(Whereas for buttons, client and server data are in separate tables: buttons and catcodes).

The sliders table contains either one or two records for every slider.

Two sliders table records: for A and B  VFOs / receivers:   abx = A    or   abx   = B

Receiver A:   .
eg: Noise reduction level 0 -15.  
     One record has: abx = A   vx = V  and   CAT command masks for VFO A   ie: RL0;   RL0tu;    RL0tu;

     One record has: abx = B   vx = V  and   CAT command masks for VFO B   ie:RL1;    RL1tu;    RL1tu;
      All other fields are identical between the two records. (except your non-functional description text)

The command masks and abx are used on the server  
Most of the remaining fields are extracted to the client at startup (text value formatting etc.)

Both client and server will have the linking code: NRLV

Note the vx field

This can have value:  V, X or U. It is copied to the client at startup.

It is set to V if the associated receiver setting has different values for VFO A and VFO B.

By this I mean that the radio holds a different value for each VFO.

Setting vx = V instructs the client to message the server with the identity of the current VFO (A or B).

Setting vx = V instructs the client to store the latest value for each VFO    See:  Dual VFO switching

At startup, a message is sent to the server to generate a data array of client-required fields for all the sliders.

Only one record is needed for the pair of sliders  . so the first encountered is extracted and the second is ignored
(The data for the client is identical between the records anyway)

If one sliders table record:   for sliders that are not VFO A/B dependent

eg: Vox gain, RF power

For these,   abx = X   vx = X

If abx = A or B  then the client sends A or B according to current VFO selection.

If abx =  X  then the client sends abx = X

buttons

For buttons, we have two separate tables:

 - catcodes   for the server data        NB  catcodes also records for FREQ (frequency read and write)

Why different to sliders?  ie: two tables rather than one?   - This is partly developmental.
 - but also because we can have large groups of buttons on the client linking to either one or two

   server records to transmit the code of the pressed button in the group.

The buttons table has an action field with values:   U, S, T G, M, R  (drop down list selector).

These act as follows

• U        Unused
• S        Single action (momentary action) button (no data), eg:   swap VFOs
• T        Toggled buttons. Changes state at every press, On/Off  - illuminates when on.
         Client stores current state in order to send appropriately on or off when pressed.
         Uses fields von and voff (usually 1 and 0)
• G        Grouped. A number of buttons in a group. Only one selected at a time.
         All have action = G and a common code field
         eg: Attenuator: 0dB, 6db, 12dB, 18dB  .. send ( and receive) data =  0 to 3 in nans and nset

       Common code field is ATTN.   ATTN is the link to a pair of catcodes records with code = ATTN,

one with abx = A for VFO A and one with abx = B for VFO B.

• M        The five grouped Tx meter records  - these specify which Tx metering value will be read from
         from the radios by the repetitive meter reading process on transmit.

The captions of these five buttons are in the meter table.   They are user configurable to allow
       the user to select which of the available metering options to offer on the buttons.

• R        The reset buttons for nine sliders. They are internally linked to the adjacent slider.
         They set the slider to the def value extracted to the client from the sliders table.

 

To repeat .... for Grouped buttons:

We have a group of buttons in the buttons table, each with a shared value for the code field.
The group has action = G and a common code (eg: ATTN)

We have two records in catcodes with code = ATTN and abx = a for VFOa and abx = B for VFO B.

Note that the client sends code = ATTN     and abx = the current VFO  ie:   A or B.

(Setting vx = V makes instructs the client to do this, ie: send current VFO identity) 

Non A/B buttons

eg: Vox on/off, processor on/off   - VFOA, VFOB, SWAP A/B, A >B,  B>A, Split

These buttons have a single record in the catcodes table with abx = X

The vx field in the buttons table

This has values U, V or X.

It controls how data is sent to client (ie: whether to send current VFO selection (A / B)
and if and how to store the buttons state on the client for fast VFO switching.

• U        Prevents participation in control state storage and retrieval on client.
         May or may not send data to server.
         Used for: Band buttons, meter buttons and slider reset buttons.
• V        WIll send abx = A or B to server, according to current VFO selection.
         Enables buttons to participate in state storage and then retrieval on VFO change
         with stored A and B values.
• X        Will send abx = X to the server.  Not A / B dependant. Not stored for VFO A/B switching.

MODE button and button groups caution.  

This discusses a button group where we have not provided a button for all the options on the rig.

 

Example:  My FTdx101D has fifteen modes.

I provided only seven mode buttons configured as a group linked to seven of the fifteen modes.

If I do all my mode selection on piWebCAT, then there is no problem.
If, on the rig, I select a mode that has no corresponding piWebCAT button, then the message
box below will appear as piWebCAT starts or when the such a mode is first selected on the rig.

The message only appears once and then is suppressed until you restart piWebCAT.

   

A similar generic message box will appear if the problem arises in other button groups.
The box occurs on start up OR the box appears if the unrecognised condition is subsequently selected

on the rig, but only if the button group has active=S which is sync mode for regular updates.

FTdx101D AGC speed has a particular problem:

I provide three buttons, fast, medium and slow code 1,2 and 3.
The received AGC data from the rig is 1,2 and 3   AND   4 = fast auto, 5 = med.auto and 6 = slow auto.

piWebCAT has a solution to this. The matching code for grouped button received data is in field nans.

nans can in fact hold multiple values, all of which result in selection of the associated button.

Multiple values are separated by an | character, eg: 4 | 5 | 6 which means  = 4 or 5 or 6.

Spaces are optional,  ie: 4|5|6 is also valid. ( |  is the OR symbol in C, PHP and javascript languages)

So we have two options:

1. Use  the three buttons, set nans equal to:   1 | 4 for fast,    2 | 5 for medium   and 3 | 6  for slow.
2. Use four buttons: auto, fast, medium and slow and set nans equal to  4 | 5 | 6 for the auto button.

For the piWebCAT direct configuration I use option 2.

With Hamlib and FTdx101D, rigctld returns 6 for all auto setttings (so I set nans = 6 for the auto button.)

To prevent the auto button sending code 0 (= AGC OFF!),  I set nset = 'xxx' which blocks any action.