Harkwood Services cmdBridge User manual

cmdBridge®
Harkwood Services Ltd
Reference Manual
Intelligent command protocol translaon

2 of 24
FCC Class A Noce
This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to
part 15 of the FCC rules. The Class A limits provide reasonable protecon against harmful interference when
the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio
frequency energy and, if not installed and used in accordance with the instrucon manual, may cause harmful
interference to radio communicaons. Operaon of this equipment in a residenal area is likely to cause
interference. This interference must be corrected at the expense of the user.
About cmdBridge
cmdBridge is a device to assist with the maintenance and management of audio / video (AV) systems. When
deploying cmdBridge a target device, under the control of an AV control system, can be easily replaced without
the need to re-program the control system. It also enables such equipment exchanges where the source code
of the control system is unavailable. This enables maintenance and support companies to provide customer
support to a wide range of customer equipment, whilst retaining a more limited spares / loan stock.
cmdBridge can also be deployed to extend the life of systems where the original control system source code is
unavailable, or the system cannot be easily updated. For example, a complex room join requires new displays
but the original source code is unavailable, cmdBridge can be deployed without the need to re-program the
enre system.
cmdBridge may also be used as a diagnosc tool, monitoring the communicaon between a control system and
target device, to help with troubleshoong.
Firmware version informaon
This manual covers rmware version 1.0.x, if upgrading to a newer rmware version please ensure you obtain
the current manual from the support secon of the website.
Standards compliance
FCC CFR 47 Pt 15 B Code of Federal Regulaons: Pt 15 Subpart B - Radio Frequency Devices - Class A
EN55032:2012
EN61000-3-2:2014
EN61000-3-3:2013
EN55024:2010
cmdBridge is RoHS compliant and lead free
cmdBridge is a registered trademark of Harkwood Services Ltd.
Designed and manufactured in the UK by Harkwood Services Ltd.
© Harkwood Services Ltd, 2019

3 of 24
Document Conven ons
The following no  ca ons are used within this manual
CAUTION Iden  ca on of ac ons required to ensure correct opera on of equipment and prevent
damage
NOTE Provides informa on speci c to a par cular item
TIP Provides helpful informa on rela ng to opera on of con gura on
Commands entered via the console end with a Carriage Return which is ASCII code 13 or 0x0D, as in the
example below;
show config<cr>
Transla on con gura on  le data is shown in the format below;
command {
source_cmd = “6F 6E 65”;
target_cmd = “6F 6E 65 20 6F 75 74 70 75 74”;
reply {
desc = “1st reply to command 1”;
target_reply = “72 65 70 6C 79”;
source_reply = “72 65 70 6C 79”;
flag = default;
}
reply {
desc = “2nd reply to command 1”;
source_reply = “69 74 20 77 6f 72 6b 65 64”;
}
}
end

4 of 24
Introducon
About this manual
This manual describes the installaon, conguraon, funcons, and operaon of cmdBridge.
Features
RS-232 Ports - Bi-direconal RS-232 ports with oponal hardware ow control. Presented on
3.5mm pitch phoenix connecons.
Ethernet Switch - Integral 2 port 10/100 Ethernet switch with Auto MDI-X automac crossover
support.
TIP Either port may be used to connect cmdBridge to a network.
USB Type A - USB type A port for the connecon of USB memory scks, to import / export
conguraon data sets.
NOTE Supported le systems are FAT and FAT32
USB Mini-B - USB Mini-B console port presenng as serial over USB for system conguraon
and monitoring. This port can also be used to supply power so conguraon does not require an
external power supply.
Power IN - 12v DC power supply, this port takes precedence over Mini-B USB power.
CAUTION Ensure to check the polarity of the connecon before applying power.
Status Lights - Indicator lights provide a quick view of port status, physical connecon type, and
data moving through the system. The lights have an adjustable brightness level.
Pass-through Mode - enables physical interface translaon between RS-232 to IP or IP to RS-232,
without altering the data.
Translaon Mode - enables translaon between the source and target devices
Capture Mode - Listens and creates a template conguraon le based on communicaon
observed.
Internal Storage - Space to keep mulple translaon sets internally. No requirement to keep a
USB memory sck aached for deployment.

5 of 24
CON USB
STATUS
LAN OUTPUT
INTPUT
RX TX
② ④ ⑤
③
①
Installaon
Front Panel connecons and indicators
① Console port - used to congure cmdBridge.
NOTE Console port can also be used to supply power, no external PSU is required during
conguraon or deployment if the USB power source can supply 1A.
NOTE Console port is a Serial over USB port, running at 230400 baud, 8 bits, no parity.
NOTE Do not use a USB cable of 2m or longer.
TIP Recommend serial console soware for Windows is ‘PuTTY’ and for Apple Mac computers
‘Serial’ by Decisive Taccs.
② USB Port - USB memory sck connecon to enable conguraons to be uploaded / downloaded,
captured data to be stored, and for rmware upgrades.
③ Status LED - Indicates the system mode or fault condion as below;
Green Pass-through mode
Blue Translaon mode
Red System fault, please see troubleshoong secon for details
④ LAN LED - Indicates the LAN status, the LED is lit when one or more port is connected. The LED
colour indicates the MAC address being used as below;
Green System default
Blue Custom
NOTE A solid colour indicates a IP address is set, either stacally assigned or provided by DHCP.
A blinking colour indicates DHCP is in progress.
⑤ Data in/out - Indicates that data is being received (RX) or transmied (TX) on the respecve
port, the LED colour indicates the physical interface type as below;
Green RS232 data
Blue IP data
Red TX only, the remote end is not accepng the IP connecon, no data could be sent.

6 of 24
LAN INPUT OUTPUT + -
PWR
12V
RS232
RX TX G RTS CTS RX TX G RTS CTS
⑩⑨⑥
⑦ ⑧
Rear Panel connecons and indicators
⑥ Ethernet Switch - 2 port 10/100 Ethernet switch to connect cmdBridge to an Ethernet network.
Both switch ports support MDI-X auto crossover.
NOTE CAT5e shielded or CAT6 and above cables are recommended.
TIP The switch enables cmdBridge to installed in-line with equipment without the need to have
an addional network port to be made available.
⑦ Ethernet Link - A solid yellow LED indicates a good LAN connecon.
⑧ Ethernet Acvity - A blinking green LED indicates LAN acvity.
⑨ RS-232 Ports - Serial input and output ports. Connect using a 3.5mm 3 pin connector, or 5 pole
connector if hardware handshaking is required.
⑩ Power connecon - Connect a 12v DC power supply with an output of 500mA or more.
CAUTION To prevent damage verify the voltage and polarity of the power supply before turning
on.
CAUTION To prevent damage do not connect the power cable to the RS-232 ports.

7 of 24
System Con gura on
cmdBridge is designed to be installed in the signal path between a Source and Target device. The physical Input
and Output ports do not need to be the same type or speed.
Con gura on of system parameters, physical port types, the loading and saving of transla on con gura on  les
is by Command Line Interface (CLI) via the console port.
Ge� ng Started
Connect the Console Port ① to the computer used for con gura on, this will also power cmdBridge if no
external Power Supply Unit (PSU) is available.
NOTE Do not use a USB cable of 2m or longer.
Using serial console so ware connect to the Serial port created by the host OS. Con gure the port to be
230,400 baud, 8N1, no  ow control.
The normal command prompt is;
>
If there are unsaved changes to the con gura on, the prompt is;
*>
The command line interface commands are grouped into areas depending on func on.
SYS
These commands related to system wide func ons, such as se� ng the IP address, system mode,
capture and monitor func ons.
TRANS
Relate to commands handling transla ons. Transla on  les are loaded from a USB memory
s ck in port ②, they are veri ed during load. Should errors be present in the  le, a list of the
problems and their loca on in the  le is provided.
Once loaded the system may be put into transla on mode, however the transla on will be lost on
a reboot. To have a transla on available for use on system start-up, it must be saved into one of a
number of internal transla on slots.
INPUT
Commands that relate to the physical con gura on of the input port.
OUTPUT
Commands that relate to the physical con gura on of the output port.
NOTE Some commands require a reboot to become ac ve, which may be automa c. Any unsaved
changes will be lost.

8 of 24
System Commands.
help
Displays a list of commands and their func on
show config
Shows the running con gura on
save config
Saves the running con gura on
sys light <1..100>
Adjusts the brightness of the status lights on the front panel.
sys ip add <addr> <mask>
Sets the IP address when DHCP is o
sys ip gateway <addr>
Sets the system IP gateway when DHCP is o
sys ip dhcp <on | off>
Turns on or o obtaining IP details via DHCP
sys mac addr <xx:xx:xx:xx:xx:xx | default>
Set the Ethernet mac address to a speci c address, or back to default.
NOTE This command will automa cally trigger a reboot.
NOTE When a custom mac address is set, the LAN Led ④ will be blue to indicate a custom address is
set when the network is ac ve.
TIP This enables cmdBridge to take the mac address of a device being replaced, nega ng the need to
update a DHCP server that is sta cally assigning address by mac address.
sys firmware load <filename>
Uploads new  rmware, once the  le is veri ed the system will automa cally reboot.
NOTE The Status LED ③ will  ash whilst the  rmware  le is being read and veri ed.
sys mode <pass | translate>
Changes the mode of opera on from pass-through mode to transla on mode.
NOTE The Status LED ③ is blue for pass-though mode and green for transla on mode.
sys monitor <on | off>
Turns the system monitor on or o
sys capture <on | off | save>
Turns capture mode on or o , when save is used the  le is saved to the USB memory s ck with the  le
name capture.txt
input enable <ip | serial>
Sets the input port to be IP or serial
input serial speed <baud>
Sets the input port serial speed
input serial flow <on | off>
Sets the input port hardware  ow control

9 of 24
input serial line <linectl>
Sets the serial line control, for example 8N1
input ip port <port>
Sets the IP port the input port will listen on for a connec on from the Source equipment.
output enable <ip | serial>
Sets the output port to be IP or serial
output serial speed <baud>
Sets the input port serial speed
output serial flow <on|off>
Sets the input port hardware  ow control
output serial line <linectl>
Sets the serial line control, for example 8N1
output ip add <x.x.x.x> <port>
Sets the output port Target device IP address and port to connect to
list usb <filespec>
List the  les on the USB memory s ck a ached to USB port ②. An op on  lespec may be used to limit
the list, e.g. *.txt
trans loadfile <filename>
Reads a transla on  le from the USB memory s ck a ached to USB port ②. Any errors in the  le will be
displayed as the  le is veri ed.
trans clear
Clears the current transla on.
trans loadslot <1..32>
Loads a transla on from one of the internal storage slots.
trans saveslot <1..32>
Saves the current loaded transla on into the indicated slot, any exis ng transla on in the speci ed slot
will be overwri en.
trans clearslot <1..32>
Clears the transla on stored in the speci ed slot.
trans list
List the transla on stored internally
trans copyslot <1..32> <filename>
Copy the transla on stored in the speci ed slot to a memory s ck a ached to USB port ②.
reboot
Reboots cmdBridge
NOTE any unsaved changes will be lost.
factory reset <config | all>
Resets cmdBridge back to factory default.
Con g resets just the con gura on leaving stored transla ons intact.
All resets both the con gura on and all stored transla ons.
NOTE This command will automa cally trigger a reboot.

10 of 24
Physical input / output ports
Source devices connect to input ports and Target devices connect to output ports. The physical port
con gura on is independent to the transla on.
The types of port used may be independent or the same, bu ering is used to process commends where the
speeds of the interface vary.
Input Output
Serial Serial
Serial IP
IP Serial
IP IP
Serial Ports
Supported serial speeds are 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
Supported line control op ons are;
8N1 8 bits, no parity, 1 stop bit
8N2 8 bits, no parity, 2 stop bits
8E1 8 bits, even parity, 1 stop bit
8E2 8 bits, even parity, 2 stop bits
8O1 8 bits, odd parity, 1 stop bit
8O2 8 bits, odd parity, 2 stop bits
9N1 9 bits, no parity, 1 stop bit
9N2 9 bits, no parity, 2 stop bits
Serial interfaces may have hardware  ow control enabled.
NOTE When serial data is received or transmi ed, the associated input/output LED will blink green.
IP Ports (Ethernet)
Source devices connect to the cmdBridge IP address and a speci ed port number, using the command.
input ip port <port>
cmdBridge will connect to a Target device IP address and port, using the command;
output ip add <x.x.x.x> <port>
NOTE When IP data is received or transmi ed, the associated input/output LED will blink blue.
NOTE When IP data is transmi ed, but a connec on to the target device is unavailable, the associated
output LED will blink red.

11 of 24
Transla on  les
Transla on  les enable a Source device to send commands to a Target device, with the data being translated
en-route. Likewise Target device replies are translated into Source device replies. Mul ple replies per
command are supported, combined with  ags to send replies when certain circumstances are met.
The full syntax can be found in Appendix A. Files are plain text and can be edited in a simple text editor, no
client speci c so ware is required.
Command  les consist of a header element which is followed by one, or more, commands, then an end.
Commands contain the replies linked to that speci c command.
The end of the  le is iden  ed simply with end
end
Header element
Descrip on
The start of a  le may contain a descrip on, as below.
desc = “EPSON EB-535W to NEX NP-M302WA”;
The descrip on is used to name the transla on, and is shown in the con gura on page when a
transla on is loaded. It also names a transla on slot if the  le is stored internally.
TIP Descrip ons can also be added to commands and replies, these can be used to help document a
transla on  le.
Variables
Variables may be de ned, for example to track the system status. They are numeric, and must be
declared before they are used, as below.
NOTE Up to 32 variables may be de ned.
var power = 0;
This declares a variable called power and sets it to an ini al value of 0.
Variables may set within commands and replies, and may be formed of compound statements. For
example;
set power = 5;
set counter = counter + 1;
set power = last_power;

12 of 24
CON USB
STATUS
LAN OUTPUT
INTPUT
RX TX
Source Reply Target Reply
CON USB
STATUS
LAN OUTPUT
INTPUT
RX TX
Source Command Target Command
command {
desc = “Mute OFF”;
source_cmd = “4D 55 54 45 20 4F 46 46 0D”;
target_cmd = “02 11 00 00 00 13”;
}
NOTE All command / reply data is input in hexadecimal pairs.
NOTE Commands / replies may be up to 768 bytes in size.
In the example above the source_cmd in ASCII would be MUTE OFF<cr>
Replies
Replies are context sensi ve to the last translated command. A target reply (the target_reply) is
received from the target device and translated into a source reply (the source_reply) and sent the
source device.
Transla on data element
Commands
A Command consists of the data received from the source device (the source_cmd), if there is a match
it is translated into the target command data (the target_cmd) and sent to the target device.
If no match is found the source command is discarded.
command {
desc = “Mute OFF”;
source_cmd = “4D 55 54 45 20 4F 46 46 0D”;
target_cmd = “02 11 00 00 00 13”;
reply {
desc = “Mute OFF OK”;
target_reply = “22 00 01 20 00 43”;
source_reply = “3A”
}
}
A command may have mul ple replies, they are processed in the same order as they are de ned in the
transla on  le.
If no match is found then the reply is discarded. However this behaviour can be overridden with the use
of reply  ags set for each speci c reply.

13 of 24
Reply  ags
Flags alter the way replies are processed, crea ng  exibility in replies that can be sent to the
source device, even if no actual target reply was received. The available  ags are default,
condi onal, and always.
Using a combina on of  ags and variables a local state machine can be developed within a
transla on  le, to keep track of a system state of a device.
For example, an original item of equipment may support mul ple commands to retrieve the
current status of various items, such as power status, ac ve port etc. A replacement device may
support only a single global status request. Using variables to track the state of commands as they
are received by cmdBridge, and condi onal replies, such a situa on can be easily managed.
default
If a reply is received from the target device, and there is no other match found, then send
this reply.
command {
desc = “Set Mute ON”;
source_cmd = “4D 55 54 45 20 4F 4E 0D”;
target_cmd = “02 10 00 00 00 12
reply {
desc = “Reply Mute ON OK”;
target_reply = “22 10 01 20 00 53”;
source_reply = “3A”;
flag = default;
}
}
always
Always send this reply, even if there is no actual reply from the target device.
command {
desc = “Set Mute ON”;
source_cmd = “4D 55 54 45 20 4F 4E 0D”;
target_cmd = “02 10 00 00 00 12
reply {
desc = “Reply Mute ON OK”;
source_reply = “3A”;
flag = always;
}
}

14 of 24
conditional
Send this reply if the speci ed condi on evaluates as true, even if no actual reply from the
target device is received.
command {
desc = “Get Mute status”;
source_cmd = “4D 55 54 45 3F 0D”;
reply {
desc = “Variable based reply, off”;
source_reply = “4D 55 54 45 3D 4F 46 46 3A”;
flag = conditional;
if (mute == 0);
}
}
Within the if statement the following tests are available;
== is equal to
!= is not equal to
&& logical AND
|| logical OR
Statements may also be compounded, for example;
if ((mute == 0) && (power == 1));

15 of 24
The complete example below shows how variables and condi ons can be used to perform status tracking of
events.
desc = “EPSON EB-535W to NEX NP-M302WA (mute example)”;
var mute = 0;
command {
desc = “Set Mute ON”;
source_cmd = “4D 55 54 45 20 4F 4E 0D”;
target_cmd = “02 10 00 00 00 12”;
reply {
desc = “Reply Mute ON OK”;
target_reply = “22 10 01 20 00 53”;
source_reply = “3a”;
set mute = 1;
}
}
command {
desc = “Set Mute OFF”;
source_cmd = “4D 55 54 45 20 4F 46 46 0D”;
target_cmd = “02 11 00 00 00 13”;
reply {
desc = “Reply Mute OFF OK”;
target_reply = “22 11 01 20 00 54”;
source_reply = “3a”;
set mute = 0;
}
}
command {
desc = “Get Mute status”;
source_cmd = “4d 55 54 45 3f 0D”;
reply {
desc = “Variable based reply, off”;
source_reply = “4d 55 54 45 3d 4f 46 46 3a”;
flag = conditional;
if (mute == 0);
}
reply {
desc = “Variable based reply, on”;
source_reply = “4d 55 54 45 3d 4f 4e 3a”;
flag = conditional;
if (mute == 1);
}
}
end

16 of 24
Managing Transla ons
Loading transla ons
Transla ons can be loaded one of two ways;
1. During con gura on from a USB memory s ck inserted into port ②. If the  le parsed
without error, then the  le is available for use. Files loaded directly from the memory s ck
are vola le and will not be loaded on a reboot. To load a  le use;
trans loadfile <filename>
Once a  le has been successfully parsed, the loaded  le may then be stored internally into
one of a number of transla on slots. Only transla ons held in a non-vola le internal slot
may be loaded automa cally on start-up. To save the currently loaded transla on  le to a
slot use;
trans saveslot <1..32>
2. From an internal non-vola le transla on slot, using the command;
trans loadslot <1..32>
Only transla ons loaded from an internal slot may be loaded automa cally on start-up
Storing transla ons
Transla ons can be stored in non-vola le internal transla on slots. To be able to store a transla on it
must  rst be loaded from a USB memory s ck inserted into port ②. Only the  le is successfully parsed
without error can the  le be stored in a non-vola le slot. To save the currently loaded transla on  le to
a slot use;
trans saveslot <1..32>
NOTE Up to 32 internal slots are available.
Clear Transla on
To clear the currently loaded transla on, regardless of source, use;
trans clear
To clear a transla on stored in a non-vola le slot, use;
trans clearslot <1..32>
Copy Transla on
A transla on stored in a non-vola le internal slot may be copied to a USB memory s ck inserted into
port ②. To copy the slot use;
trans copyslot <1..32> <filename>
This will copy the transla on  le from the speci ed slot to the speci ed  lename.

17 of 24
Monitor Mode
cmdBridge may also be used as a diagnos c tool, enabling communica on between a source and target device
to be monitored.
Data received is displayed, in real  me, to the console port in ASCII and HEX, from the physically con gured
input and output ports. The data is shown to be on the logical interface received.
The physical input and output ports can be serial or IP, depending on requirement.
NOTE Monitor may be used even if transla on mode is ac ve, so transla ons may also be viewed in real  me.
The output is displayed on the system console, as hex data and as ASCII if printable. Non printable characters
are replaced with a full stop.
Example of captured data;
Source Command IN :
50 57 52 20 4F 4E 0D PWR ON.
Target Reply IN :
4F 4B 0D OK.
Capture Mode
Capture mode can be used to help create transla on  le templates. When inserted in the data path of a
working system, and capture mode ac vated, cmdBridge will record all the commands and associated replies
between the source and target device.
The captured data may then be saved to a USB memory s ck in inserted into port ②, in the transla on  le
format. This  le, in essence, gives one half of the transla on  le in a ready to use format to create a working
transla on matrix.
This can help, for example, when taking on a new maintenance contract. During an ini al site visit, the exis ng
interac on between a control system and end devices can be captured. Transla on  les can then be created to
match this against the company loan stock, enabling rapid deployment of cmdBridge as and when required.
NOTE Capture mode is only available when in pass-through mode.
During capture the various commands and replies have their descrip on  eld  lled with the command number,
and associated replies are also numbered. All data is with reference to the source device, as it would be when
forming part of a transla on  le.
To use Capture mode use the following command;
sys capture <on | off | save>
on Turns capture mode on
off Turns capture mode o
save Saves the data to a memory s ck in inserted into port ②, with the  le name capture.txt
NOTE When turning capture mode on, any previous captured data in memory is deleted.

18 of 24
An example of captured data;
desc = “Automatically Captured Data”;
command {
desc = “Command 1”;
source_cmd = “00 85 00 00 01 01 87”;
reply {
desc = “Reply 1”;
source_reply = “20 85 01 20 10 FF FF 00 00 00 00 00 00
00 00 00 00 00 00 00 00 D4”;
}
reply {
desc = “Reply 2”;
source_reply = “20 85 01 20 10 00 00 00 00 00 10 FF FF
00 00 FF FF FF FF FF FF DE”;
}
}
command {
desc = “Command 2”;
source_cmd = “02 00 00 00 00 02”;
reply {
desc = “Reply 1”;
source_reply = “22 00 01 20 00 43”;
}
}
end
Firmware Update
cmdBridge  rmware is updated via a USB memory s ck inserted into port ②. Firmware is uploaded with the
command;
sys firmware load <filename>
Once the  le has been veri ed, cmdBridge will reboot and the  rmware will be upgraded. This process cannot
be interrupted.
CAUTION Do not power o cmdBridge whilst the  rmware is uploading.
NOTE The Status LED ③ will  ash whilst the  rmware  le is being read and veri ed.
NOTE The Status LED ③ will go green and the Input / Output RX and TX lights will cycle in a green circular
pa ern to indicate the  rmware wri ng is in progress.
Should a  rmware upgrade fail, the system will revert to the last previously veri ed  rmware automa cally.

19 of 24
Troubleshoong
Translaon le errors
During the loading of a translaon le it is parsed to ensure it is correctly formaed. Should an error be
idened within the le this is reported back to the console, along with the approximate line number of
where the error is located. Mulple errors may be reported during vericaon.
The errors relate to either the le syntax, or values being out of bounds. The errors are self explanatory
but may have been caused by a missing semi-colon or bracket further up the le than the indicated line
number.
System fault indicaon
System faults are indicated when the Status LED ③ is red. The specic fault is indicated by another LED
being lit and it’s colour.
LED Colour Issue
Lan Red The Ethernet ports could not be inialised.
If the problem persists following a power cycle the unit will require service.
Input RX Red The internal storage card has failed to read or write.
If the problem persists following a power cycle, please contact support for
assistance.
CAUTION Do not aempt to swap the internal storage card for a generic
card, or the unit will not operate correctly.
Firmware update rmware recovery
CAUTION This method will erase ALL non-volale and conguraon data. It cannot be reversed.
CAUTION This procedure should ONLY be performed if a normal rmware upgrade procedure is not
possible.
To recover cmdBridge from a failed or faulty rmware upgrade, this procedure may be performed to
eect a total system reset. This will;
Revert cmdBridge to the original factory shipped rmware image
Clear any and all stored translaons
Clear the system conguraon
Connect the Input Serial port RX line to the Output Serial port RTS line with a link cable, then turn the
system on. Once the rmware wring procedure starts (the Input / Output TX and RX LEDs start to
cycle), remove the link cable.

20 of 24
Appendix A
Translaon le syntax
The syntax for translaon les is provided below as rail road diagrams.
source_commands
Translaon
desc = quoted_string ;
var variable_name =number ;
source_commands end
command {
desc = quoted_string ;
source_cmd = hex_data ;
target_cmd = hex_data ;
set variable_name =set_variable_expression ;
target_replies
}