Communicating with a Barco projector over network. Technical note

Transcription

1 Communicating with a Barco projector over network Technical note MED /00 12/06/2008

2 Barco nv Media & Entertainment Division Noordlaan 5, B-8520 Kuurne Phone: Fax: Visit us at the web: Printed in Belgium

3 1. General 1. GENERAL 1.1 Introduction Introduction This technical note explains how you can setup and communicate with a Barco projector using the LCD/DLP protocol over a TCP/IP network. This technical note focuses on Barco Events projector series that support network communication: XLM, FLM, CLM, and SLM. Copyright This document is Copyright 2008 by Barco Media & Entertainment. No part of this document may be copied, reproduced or translated. It shall not otherwise be recorded, transmitted or stored in a retrieval system without the prior consent of Barco. Disclaimer Barco provides this technical note as is without warranty of any kind, either expressed or implied, including but not limited to the implied warranties or merchantability and fitness for a particular purpose. Barco may make improvements and/or changes to the product(s) and/or the program(s) described in this publication at any time without notice. This publication could contain technical inaccuracies or typographical errors. Changes are periodically made to the information in this publication; these changes are incorporated in new editions of this publication. Audience This technical note is intended for software programmers and system integrators that want to be able to control a Barco projector from their own application, over a TCP/IP network. This document expects a basic knowledge of TCP/IP networking and some knowledge of programming language. The examples in this document are written in Java. Feedback Feedback is most certainly welcome for this document. Please send your additions, comments and criticisms to the following address: events.techsupport@barco.com. Trademarks Java is a registered trademark of Sun Microsystems, Inc. MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008 1

4 1. General 2 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

5 2. An introduction to the Barco LCD/DLP protocol 2. AN INTRODUCTION TO THE BARCO LCD/DLP PROTOCOL Intro The base for all communication is the Barco LCD/DLP protocol. This protocol has been used on serial communication but is now also used for network based communication. This section explains this protocol in brief. More information about the protocol itself can be found in the document "Serial Communication LCD-DLP Projector" (see "Further information", page 15). 2.1 Command structure command structure Each command is packaged in this structure: 0xFE Start byte (1 byte) ADDR Device address (1 byte) PREFIX Prefix (0..n bytes) CMD Command (1..n bytes) DATA Data (0..n bytes) CHK Checksum (1 byte) 0xFF Stop byte (1 byte) Explanation The start and stop byte are used to let the receiver know that a command is starting or has stopped. Device address is used when multiple devices are connected on the same physical connection. This is typically used with serial connections. In case of Ethernet connections this should be set to 0. Prefix bytes: for some special commands it is possible to use prefix bytes before the actual command bytes. It depends on the actual protocol implementation which prefixes are available and when they can be used. Command bytes: there will be at least one byte per command. The command bytes actually tell the device what to do. Data bytes: this is optional and depends on the command that will be sent. See also Data bytes chapter. Checksum byte: this byte is used to detect errors in the transmission or reception of the command. 2.2 Bytes mark up and examples Any command byte, data byte or checksum byte that equals 0x80, 0xFE or 0xFF, has to be marked up for transmission with a leading 0x80. Example 1 : Byte to send: 0x80 Actual bytes to send after mark up: 0x80 Example 2 : Byte to send: 0xFE Actual bytes to send after mark up: 0x80 0x7E Example 3 : Byte to send: 0xFF Actual bytes to send after mark up: 0x80 0x7F Example 4 : Bytes to send: 0xFE 0xFF 0x80 Actual bytes to send after mark up: 0x80 0x7E 0x80 0x7F 0x80 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008 3

6 2. An introduction to the Barco LCD/DLP protocol 2.3 Characters and character strings When characters need to be sent in the data section of a command, we use ANSI encoding (ASCII) for sending each character as abyte. Formatting Character strings can be formatted in two ways: C-style strings Pascal-style strings C-style format An array of one or more characters which is terminated by a NULL character (). The position of the NULL character determines the length of the string. Example: f o o b a r Pascal-style format An array of one or more characters. The first byte of the string indicates the length of the string. Therefore pascal-style strings are limited to 255 characters. Example: 0x07 f o o b a r 2.4 Multi-byte values A multi-byte value consists of more than one byte where the first byte is the Most Significant Byte (MSB). Example of a 4-byte value: 0x01 0x20 0x50 0x30 = (0x01 * 256^3) + (0x20 * 256^2) + (0x50 * 256) + (0x30) = (1 * ) + (32 * 65536) + (80 * 256) + 48 = = Checksum The checksum value for a command is calculated by doing a modulo 256 on the sum of the byte values of all bytes between start of the command and the checksum byte. Checksum calculation Checksum = (ADDR value + PREFIX values + CMD values + DATA values) mod Acknowledgement (ACK and NACK) If a command is received, the receiver will check the validity and correctness of the command before processing it. If the command is understood, the receiver will first acknowledge the command before doing the actual processing of the command. This command is called the ACK: ACK (ACKnowledge) Command[0] Command[1] 0x06 4 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

7 2. An introduction to the Barco LCD/DLP protocol An ACK is sent when these conditions are met:: The command format is correct The command and its parameters are valid The checksum is correct If one of these tests fail, the receiver will send a NACK: NACK (Not ACKnowledge) Command[0] Command[1] 0x Command response A lot of commands do not only return an ACK or NACK, but also return a response or reply. This reply will be sent after processing the command. The answer will have the same command bytes as the request, but typically the data bytes will contain the response information. It depends on the protocol implementation whether a command requires a reply or not. This will be defined per command in the protocol. Example 1: the client wants to know the type of the projector. It sends the projector, read type command. The projector will acknowledge the command and then send the type in response. Read type Client ACK Response Projector Image 2-1 Request:: Start byte: Device address: Checksum: Stop byte: 0xFE 0x6b 0x6b 0xFF Acknowledge: Start byte: Device address: Command[1]: Checksum: Stop byte: 0xFE 0x06 0x06 0xFF Reply: Start byte: Device address Data[0]: Data[1]: Data[2]: 0xFE 0x6b 0x42 = B 0x41 = A 0x52 = R MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008 5

8 2. An introduction to the Barco LCD/DLP protocol Data[3]: 0x43 = C Data[4]: 0x4f = O Data[5]: 0x20 = Data[6]: 0x46 = F Data[7]: 0x4c = L Data[8]: 0x4d = M Data[9]: 0x20 = Data[10]: 0x48 = H Data[11]: 0x31 = 1 Data[12]: 0x38 = 8 Data[13]: Checksum: 0xA2 Stop byte: 0xFF Example 2: the client sends a command with a wrong checksum. The projector will reject the command by sending a NACK. Unknown cmd Client NACK Projector Image 2-2 Request:: Start byte: Device address: Checksum: Stop byte: 0xFE 0x6b 0xFF Not acknowledge: Start byte: Device address: Command[1]: Checksum: Stop byte: 0xFE 0x15 0x15 0xFF Example 3: client sends an update of the brightness. The projector will acknowledge but as this command does not have a response, that s where the communication stops. Request:: Start byte: Device address: Command[1]: Checksum: Stop byte: 0xFE 0x20 0x02 0x22 0xFF 6 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

9 2. An introduction to the Barco LCD/DLP protocol Acknowledge: Start byte: Device address: Command[1]: Checksum: Stop byte: 0xFE 0x15 0x15 0xFF MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008 7

10 2. An introduction to the Barco LCD/DLP protocol 8 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

11 3. Communicating with the projector over network 3. COMMUNICATING WITH THE PROJECTOR OVER NETWORK Introduction When supported by the projector, it is possible to communicate with a projector over a TCP/IP network. The communication follows a Client/Server model where the projector is the server. This means that the projector responds on requests that are sent by a client. The projector will not send out requests on its own initiative. The communication is blocking which means that when a request is sent to the projector, no other requests can be sent until the projector has responded on the first request. The communication blocks for each request. 3.1 Making connection with the projector The projector is listening on TCP port 0xAAA0 (43680) for incoming connections. The IP address can be retrieved using the local user interface of the projector or the OSD menu. To make a connection, you need to create a TCP socket connection with the projector on port 0xAAA0. Note that for Digital Cinema projector based on TI Series II, this will be a different port. 3.2 Sending a message How to send Messages should be send in the LCD/DLP protocol format. This means that each command needs to be structured in the correct way, before it is being sent to the projector: The projector address must be set to 0. A correct checksum value must be generated for the command, based on all the bytes between the start byte and the checksum byte. 3.3 Receiving an answer When receiving the answer from the projector, you should always first read the acknowledgement of the request. Only when the request has been acknowledged, you can expect the actual response (if any). MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008 9

12 3. Communicating with the projector over network 10 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

13 4. Advanced communication techniques 4. ADVANCED COMMUNICATION TECHNIQUES 4.1 Projector discovery How to discover It is possible to discover all the projectors on the network using a UDP broadcast. UDP broadcast only works on IP networks and requires a special socket connection: the datagram connection. Projector 1 Projector 2 Client LAN Projector n Image 4-1 To discover the projectors, send a datagram packet to the broadcast address and port 0xA001. The packet should contain 1 byte: \\x3f, which is the ASCII character?. All the devices that support UDP broadcast discovery, will answer on the request by sending an array of (C-language) strings on the same socket. Each string is represents a key-value pair with specific information about the projector that has been discovered. Typically, following strings will be returned: hostname=value: the hostname of the projector ip-address=value: the IP address of the projector mac-address=value: the MAC address of the NIC on the projector type=value: the projector type (not for DP90/DP100 projectors) Remarks: The broadcast does not follow the typical LCD/DLP protocol formatting: the request is just one byte (not marked up as LCD/DLP command) and the devices answer back without sending an ACK and without formatting their response in the protocol command format. The size of the array is undetermined, but in most cases it will contain 4 strings. However, this is open to future expansion, so more strings may be added later. The strings normally appear in this order: hostname, ip-address, mac-address and type, but this cannot be guaranteed. The broadcast that is used is a limited broadcast. This means that the broadcast message is transmitted to all network interface cards (NIC s) which are on the same IP segment as the client. This type of broadcast is not forwarded by routers so it will not detect devices which are on another segment. MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/

14 4. Advanced communication techniques 4.2 Answer prefix The projector always responds when a question is asked (query or read operation) but in case of write operation the projector will not send back a response. If you want to get an answer about whether the write operation was OK or not, you should add the answer prefix to the command. Prefix code Prefix[0]: Prefix[1] Prefix[2] 0x03 Answer parameters. Currently there s only one used 0x02: return result When this prefix is used, the projector will respond with the prefix as command and a data byte to indicate the result. Response on a command with answer prefix: Command[1] Data[0]: 0x03 =nosuccess 0x01 = success This technique is frequently used by commands that take some time to process f.i. switching lamps on or off, moving lens, shutter,... Example This example shows the request and responses when sending a brightness, write command with the answer prefix. Request : Prefix[0]: Prefix[1] Prefix[2] Command[1] 0x03 0x02 0x20 0x02 Acknowledge: Command[1] 0x06 Reply: Command[1] Data[0]: 0x02 0x01 12 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

15 5. Code sample 5. CODE SAMPLE 5.1 Java code sample This code sample in Java contains a small program that will connect to a projector and send the command to switch the lamps on (lamp status, write). Java code /* * SimpleConnect.java * * Copyright 2008 Barco NV. All rights reserved. * BARCO PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package com.barco.connect; import java.io.*; import java.net.socket; /** * Sample code shows how to connect to a projector and switch the lamps on. */ public class SimpleConnect private static final int PORT = 0xAAA0; private Socket connection; private OutputStream out; private InputStream in; public static void main(string[] args) SimpleConnect sc = new SimpleConnect(); try // make connection with projector sc.connect(" "); // send command to switch lamps on byte[] arr = new byte[9]; arr[1] = ; // device address arr[2] = ; // answer prefix (1) arr[3] = 0x03; // answer prefix (2) arr[4] = 0x02; // answer prefix data (send result) arr[5] = 0x76; // command byte (1) arr[6] = 0x1A; // command byte (2) arr[7] = 0x01; // data byte (0x01 = switch lamps on) arr[8] = sc.generatechecksum(arr); arr[0] = (byte) 0xFE; arr[9] = (byte) 0xFF; // write request sc.writebytes(arr); System.out.println("Sent command to switch lamps on"); // wait for acknowledgement if (!sc.readacknowledge()) System.out.println("Command not ACK ed"); return; System.out.println("Command acknowledged."); // wait for answer result int result = sc.readanswerresult(); System.out.println("Command result = " + result); if (result == 0x01) System.out.println("Lamps successfully switched on."); catch (IOException e) System.err.println("Communication error: " + e.getmessage()); finally MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/

16 5. Code sample try sc.disconnect(); catch (IOException e) // failed to disconnect /** * Connects with the projector on the supplied address * address * The IP address of the projector */ public void connect(string address) throws IOException // make connection connection = new Socket(address, PORT); out = connection.getoutputstream(); in = connection.getinputstream(); /** * Breaks the connection with the projector. */ public void disconnect() throws IOException if (connection!= null && connection.isconnected()) out.close(); in.close(); connection.close(); /** * Writes all the bytes in the array to the device. * arr * The byte array IOException * When writing data to the stream failed */ public void writebytes(byte[] arr) throws IOException if (connection!= null && connection.isconnected()) out.write(arr, 0, arr.length); /** * Reads data until an ACK or NACK is received * true if the command has been acknowledged, false if the command * is not acknowledged or if there s no connection. IOException * When reading data from the stream failed. */ public boolean readacknowledge() throws IOException if (connection!= null && connection.isconnected()) int c = in.read(); while (c!= -1) if (c == 0xFE) // start reading command int deviceaddress = in.read(); int cmd1 = in.read(); // should be int cmd2 = in.read(); // is either 0x06 or 0x15 if (cmd2 == 0x06) // got ACK return true; else if (cmd2 == 0x15) // got NACK return false; else // read next byte c = in.read(); 14 MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/2008

17 5. Code sample return false; /** * Reads data until an answer response is sent by the device. * The result of the answer response, -1 if no (valid) answer has * been received or when there s no connection. IOException * When reading of data from the stream failed. */ public int readanswerresult() throws IOException if (connection!= null && connection.isconnected()) // read response int result = -1; int c = in.read(); while (c!= -1) if (c == 0xFE) // start reading command int deviceaddress = in.read(); int cmd1 = in.read(); // should be int cmd2 = in.read(); // should be 0x03 result = in.read(); // the result data byte return result; else // read next byte c = in.read(); return -1; /** * Generates a checksum of all the bytes in the array. * arr * The array of bytes The checksum. */ public byte generatechecksum(byte[] arr) int sum = 0; for (int i = 0; i < arr.length; i++) sum += arr[i]; return (byte) (sum % 256); 5.2 Further information More information about the LCD/DLP protocol and the list of specific commands for each projector, can be found on the Barco PartnerZone. Here are some titles and article numbers of the most frequently used manuals: Serial Communication LCD-DLP Projector (R ) RS232 Commands for CLM R10+ (R ) RS232 Commands for FLM R20+ (R ) RS232 Commands for XLM and DP series (R ) MED COMMUNICATING WITH A BARCO PROJECTOR OVER NETWORK 12/06/