VISCAoverIP Controller for Cisco PrecisionHD Cameras

This project creates a controller that can be attached to (hopefully) any VISCA capable camera. It implemends the VISCAoverIP protocol utilizing UDP or TCP (since v0.3) as transport. The device will output VISCA commands using a UART on Pins 16 and 17 by default.

The whole application has been implemented synchronously on purpose, as we have a good chance that we catch all responses from the cam and can route them back to the client with the correct sequence number this way.

Since Version 0.2 the controller opens a hotspot called VISCAoIP-ChipID if no Wifi is configured or unreachable. The Password of the AP is hard coded as "viscasetup". After setup, you can recall the setup by closing GPIO19 to GROUND before starting and holding it closed until the LED flashes quickly. Open the circuit before the LED turns off again, and the setup assistant will be shown. If you keep GPIO19 closed for about 7 seconds while the LED flashes quickly, a full reset will be performed.

The project is working but some improvements will likely come.

Additional Features

By default, the controller will log all communication to the serial interface (USB terminal) at 115200 Baud. See below. By setting consoleMode to 1 in the code, you can change this behavior so that the USB interface will act as a VISCA passthrough. This way, you can control the cam directly via USB if you want. By setting it to 0 you can disbale all console output from the loop - The startup is still logged.

For Cisco PrecisionHD cameras, the controller can store PTZF-Presets, when the ENABLE_CISCO_PTZF_PRESETS_HACK define is kept in the header. These presets work using the official VISCA commands for storing and recalling. Just set the camera to the desired position and send a 8101043f01XXFF to save, or 8101043f02XXff to recall preset XX. The controller accepts 00 up to FF as preset number, so 256 presets would be possible, but you might hit the storage capacity limit of your ESP...

Serial Console Log

When consoleMode is set to 2 (default value), you will see all communications on the serial monitor connected via USB. The first two signs indicate what type of packet the line is showing. A space seperates indicator and packet value (hex'ed). The possible packet types are:

• V> -> VISCA from controller to camera (RS232)
• V< -> VISCA from camera to controller (RS232)
• U> -> UDP Packet from client to controller
• U< -> UDP Packet from controller to client
• T> -> TCP Packet from client to controller
• T< -> TCP Packet from controller to client

Required Hardware

Of course you need a capable camera, and:

• Some cable pieces
• One RJ45 connector (or a half cable)
• ESP32 NodeMCU Board
• MAX3232

Connecting the camera

By default, we use pins 16 and 17 for VISCA.

The wiring is as follows (each - is a wire):

ESP32         MAX3232      RJ45 (Brackets = Colors in LAN cables of respective standards A or B)
           TTL    RS232
GPIO16  -  TX   |  RX   -  Pin 6 (A: Solid grange / B: Solid green)
GPIO17  -  RX   |  TX   -  Pin 3 (A: Half Orange / B: Half green)
GND     -  GND  |  GND  -  Pin 2 (A: Solid green / B: Solid orange)
3V3     -  VCC

Hint: Using a voltage regulator, it should be possible to drain power for the ESP between RJ45 pins 1 (+12V) and 2 (GND).

Compatible Client Software

This controller should be compatible to any usual VISCAoIP clients. It has been tested with:

• PTZControls for OBS (UDP or TCP)
• VISCACamLink (TCP)

VISCAoIP protocols

This is a very brief description of the two supported VISCAoIP protocols. In both cases the "VISCA-Command" is the binary byte sequence, one would send to the camera on RS232.

TCP

connection is successful after SYN/ACK - no protocol initialization or protocol handshake. Transmitting to camera is as simple as sedning exactly the VISCA-Command on the TCP channel as one packet per command. No headers or alike, just plain VISCA. The response is delivered the exact same way.

UDP

The UDP implementation is a bit different. Here the packet has a header, but also no handshake. When the client connects, it SHOULD send a sequence reset packet first (Full packet as hex representation: 0200000100000000FF ) The packet header is 8 bytes long and constructed as follows:

• byte 0: always 0x01 for any VISCA payload
• byte 1: VISCA message type. 0x00 for a command, 0x01 for an inquiry, 0x11 for a reply message
• byte 2+3: VISCA message length in bytes, low endian (0x00-0x10 by standard, this controller supports up to 32 bytes by default so 0x00-0x20 is valid to fully support CISCO cameras)
• byte 4, 5, 6, 7: sequence number of this UDP packet (0x00000000 - 0xFFFFFFFF) increased on every packet sent. Controller will track sequence number and drop packets with a lower number than the highest ever resecived. On rollover or reastart, a sequence reset (see above) resets the counter.
• from byte 8: VISCA payload (the actual VISCA command) Responses are sent back to the client in the same format. byte is 0x01 and byte 2 is 0x11 for any response to the client. Sequence number in responses contains the sequence number of the packet, the response is sent for. This is done on a best effort base, sequence number relation between command and response not guaranteed especially for "completed" messages.

LED signals

Camera addressing

During startup the LED will flash in medium speed (333ms) for each addressing try. (One time for first try, twice for second try and so on) If addressing fails (no camera responded) after 5 tries, the LED will blink three times long (1000ms) and the ESP will restart. In the event of a communication error the LED will blink five times long (1000ms) and the ESP will reboot

Initialization

After successful addressing, the LED will flash one time long (1000ms) followed by the number of cameras quick (250ms) flashes. The fles will be right before initialization of the respective camera.

System Ready

When the listeners have loaded and the system is waiting for VISCA the LED will be solid on until data is received. The LED will flicker when data is received/transmitted

Known issues

• Highspeed-Mode is not working - For some reason, the camera sends "OK" but does not actually switch to 115200 baud so I disabled this for now.