TCP/IP interlock

From SmartSDR Wiki
Jump to: navigation, search

Interlock Description

The SmartSDR Interlock engine ensures that the radio does not transmit at inappropriate times. Interlock is used both for internal switching in the radio as well as for accessories such as amplifiers and antennas. There are two key ways to access interlock in the FLEX-6000 from an API standpoint. First, if the operator has plugged in something to the ACC port (DB15) on the radio or into the TX REQ line, then commands can be issued to tell the radio that these ports are to be factored into the interlock. A polarity in addition to an enable/disable are supported for the two interlocks. Essentially, when the interlock line is active (ACC or TX_REQ), the radio can enter the transmit mode, but will not supply transmit power to the output port until the interlock line is releases.

Some products that run external to the radio may prefer to negotiate interlock in software through the API entirely. The commands that govern the software interlock for external devices are interlock create, ready, enable, disable and remove. For these devices, a dynamic interlock per device can be created and then set and cleared entirely using the API. This means that no wires between the transceiver and the amplifier or antenna controller other than the ethernet cable would be required.

Hardware Interlock

Hardware interlocks are handled through the ACC and TX_REQ lines on the rear of the transceiver. The API commands for these interlocks simply enable and disable the interlock and set the polarity (active high or low) for the interlock

INTERLOCK timeout

Set the transmit timeout value. If the radio is in transmit beyond this point, the radio will automatically unkey

C[D]<seq_number>|interlock timeout=<timeout_ms>

<timeout_ms>  = the timeout value in milliseconds (60000 for one minute, for example)

Example:

C21|interlock timeout=20000

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R21|0|

INTERLOCK TXREQ Enable

The TXREQ lines are designed to stall or prevent transmit when external hardware is not ready for RF. There are two hardware TXREQ lines on the FLEX-6000 Signature Series radios, one as an RCA connector and the other as a line on the DB-15 accessory connector. Each TXREQ line may be independently enabled or disabled and each line has a polarity setting. The polarity determines the setting (high or low) in which transmit is OK.

C[D]<seq_number>|interlock acc_txreq_enable=<T|F>

<T|F>      = A 'T' or an 'F' indicating whether this TXREQ port is enabled

Note that rca_txreq_enable may be substituted for the RCA TXREQ line

Example:

C21|interlock acc_txreq_enable=T

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R21|0|

INTERLOCK TXREQ Polarity

C[D]<seq_number>|interlock acc_txreq_polarity=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Note that rca_txreq_polarity may be substituted for the RCA TXREQ line

Example:

C21|interlock rca_txreq_polarity=F

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

INTERLOCK TXx_ENABLED

Note the lowercase x is to be substituted with 1, 2, or 3

C[D]<seq_number>|interlock tx<1|2|3>_enabled=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Example:

C21|interlock tx1_enabled=F

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

INTERLOCK TXx_DELAY

Note the lowercase x is to be substituted with 1, 2, or 3

C[D]<seq_number>|interlock tx<1|2|3>_delay=<timeout_ms>

<timeout_ms> = delay value in milliseconds

Example:

C21|interlock tx1_delay=1000

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

INTERLOCK ACC_TX_ENABLED

C[D]<seq_number>|interlock acc_tx_enabled=<T|F>

<T|F>      = A 'T' or an 'F' indicating the line state for "transmit OK."  So an 'F' would indicate that it is OK to transmit if the line is 0 Volts

Example:

C21|interlock acc_tx_enabled=F

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

INTERLOCK ACC_TX_DELAY

C[D]<seq_number>|interlock acc_tx_delay=<timeout_ms>

<timeout_ms> = delay value in milliseconds

Example:

C21|interlock acc_tx_delay=1000

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK timeout value changed
50000016   Malformed command
5000002C   Incorrect number of parameters

Ethernet Interlock

Ethernet Interlocks, those created and controlled over the Ethernet, must be created and controlled using API commands and statuses. The general sequence for Ethernet interlocks are as follows:

  1. Device connects to radio as a client
  2. Device creates an interlock for itself using interlock create
  3. Amplifier interlocks immediately become not ready, Antenna interlocks start as ready
  4. Device waits for a PTT_REQUESTED state to be emitted from interlock
  5. Device becomes ready internally
  6. Device sends a interlock ready command to the radio

Example interaction between client and radio:

(1) C2|interlock create type=amp name=KZX-2500 serial=111-2500-111 valid_antennas=ANT1,ANT2'
(2) R2|0|1
(3) S0|interlock state=PTT_REQUESTED reason=AMP:KZX-2500 source=MIC tx_allowed=1
(4) C2|interlock ready 1
(5) R2|0|
(6) S0|interlock state=TRANSMITTING source=MIC tx_allowed=1
(7) S0|interlock state=READY reason=AMP:KZX-2500 tx_allowed=1

In this example, the device registers an interlock for itself (2) and the radio responds with the interlock number (2) which is #1. The user then presses the PTT causing status (3) to be emitted. The device recognizes that transmit is in progress and readies itself for transmit and then sends a ready to the radio (4). The radio responds that it received the ready (5) and switches to transmitting (6). The radio is now emitting power. The used then releases the PTT and the radio switches back to a ready state (7), but the device is in a not ready state.

INTERLOCK create

Create a dynamic ethernet interlock that will be used by an external device. Once the interlock is created, it is assumed to be enabled and the radio will immediately be NOT READY as a result. The radio will only go into the READY state after a PTT and after the device sends an 'interlock ready' command. The interlock will always be cleared back to NOT READY after each PTT release

C[D]<seq_number>|interlock create type=<interlock_type> model=<device_model> serial=<device_serial> valid_antennas=<comma_separated_antenna_list>

<interlock_type>  = the type of device requesting the interlock (see table)
<device_model>  = the model number of the device requesting the interlock
<device_serial>  = the serial number of the device requesting the interlock
<comma_separated_antenna_list> = Antennas that this interlock should apply to (for amps something like valid_antennas=ANT1,ANT2)

Example:

C21|interlock create type=AMP model=KZX-2500 serial=1234-5678 valid_antennas=ANT1

The table below shows the currently supported type parameters to the create command:

Parameter Value
AMP External power amplifier - interlock assumes a return to not_ready state after each PTT
ANT External antenna controller - interlock state always controlled by external device

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 <interlock_id> OK, <interlock_id> is the id to use in future communications (hexadecimal)
50000016   Malformed command
5000002C   Incorrect number of parameters
E2000000   Internal software error on create

Response Example:

R21|0|000000F4

INTERLOCK ready

Signal that the external device is now ready to receive RF. This is generally sent after the device received an interlock state=PTT_REQUESTED status message. Failure to send this message within the timeout period of the interlock (generally 500ms) will result in an error message indicating that the external device is preventing transmit from occurring. The error message will be displayed in SmartSDR to the user as a balloon message or sent to other clients using the Message Format in the TCP/IP command stream.

C[D]<seq_number>|interlock ready <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C24|interlock ready 000000F4

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK interlock is now ready
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R24|0

INTERLOCK disable

Temporarily disable the interlock. After this command, the radio will no longer wait for input from the remote device before sending RF. A typical use case would be to issue the disable command after an amplifier is placed into bypass

C[D]<seq_number>|interlock disable <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C25|interlock disable 000000F4

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK interlock is now disabled
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R25|0

INTERLOCK enable

Reenable a disabled interlock. After this command, the radio will return to the state right after creation of the interlock. A typical use case would be placing an amplifier back online from a bypass state.

C[D]<seq_number>|interlock enable <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C29|interlock enable 000000F4

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK interlock is now enabled
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R29|0

INTERLOCK remove

Remove a previously created interlock from the system. A typical use case would be removing the interlock before disconnecting from the radio when the amplifier is shutdown, etc. Once this command is issued, no more communications with the radio regarding this interlock_id will be accepted

C[D]<seq_number>|interlock remove <interlock_id>

< interlock_id >  = the interlock ID received when the interlock was created

Example:

C30|interlock remove 000000F4

See Response Format for details on the format of the response messages from the radio

Responses
Hex Response Message Debug Output / Meaning
00000000 OK interlock is now removed
50000016   Malformed command
5000002C   Incorrect number of parameters

Response Example:

R30|0