USB Scanner USB Scanner is a command line utility which locates arduino devices and associates them with OpenHAB Bridges. USB Scanner is supplied for free as is, with no implied conditions. You use this program as your own, exclusive risk. I will assume no responsibility as to what USB Scanner actually does. On The Other Hand, I have done testing on my own system (Windows and Linux) and it seems to work :-) You must install the drivers necessary to let your operating system map the USB connected arduino to a communications (serial) port. You will need the drivers to have OpenHAB use the arduino. I am also using a third party Java serial port library jSSC (Java Simple Serial Connector) written by Alexey Sokolov (scream3r). You can Google it for more information. ===================================================== USB Scanner scans for serials ports connected to your computer. Each arduino will have its own port. The scanner then queries each port for a unique identifier (from the arduino). Finally the scanner modifies the OpenHAB binding file, locating the correct Bridge statement and replacing the Bridge serialPort parameter with the correct port name. At this point you can start OpenHAB. Note that the scanner will add its identity information to the top of the binding file to indicate that the file was modified. The scanner will replace this line every time it runs. The identity line (with a date stamp) is: //*** USB Scanner (0.90) written 2021.11.23 14:25:38 USB Scanner uses a settings file to control its behaviour and also to set up the mapping between the arduino response and the Bridge identifier. The default name is USBScanner.ini, though you can specify a different one. USB Scanner will end with a value of 0 (normal operation) or 1 (error condition). You can trap for these values and not start OpenHAB if an error occurs. ===================================================== ** Command Line Switches USB Scanner allows for several command line switches. Note that USB Scanner recognizes both a dash and a slash for switches, so /? and -? are equivalent. If you use a command line switch, it will override the same switch in the setting file. You can get a list of the switches by typing in: java -jar USBScanner.jar /? A complete explanation of the following switches and their values are in the Setting File section below. -------------------------------------------------------------------------------------------- /s: This switch specifies the name of the settings file to use. An example would be: /s:myfile.txt -------------------------------------------------------------------------------------------- /a: /a:Report /a:Test /a:Modify -------------------------------------------------------------------------------------------- /e: /e:Quiet /e:Info /e:Debug ===================================================== ** Setting File The default setting file USBScanner.ini has a basic explanation for each setting and its values. The setting file uses the # as a comment character. Any line beginning with a # is ignored. Empty lines are also ignored. Each setting consists of a key=value pair. USB Scanner ignores white space, so you can indent settings and place extra spaces between values as you wish. Keys are not case sensitive. baudRate and BAUDRATE are equivalent DO NOT use an equals sign in any of your values! -------------------------------------------------------------------------------------------- * USB Scanner Setting file version version = 1 This is the version of the setting file. If, in the future, new settings are added, then the version will change. For this version, the number must be 1. Also the version key MUST be the first non-comment line in the file. -------------------------------------------------------------------------------------------- * Console ECHO Level echo = INFO This is equivalent to the /e: command line switch USB Scanner will echo out the console various messages as it runs. You can control the number of messages by setting the ECHO value. Possible values are: QUIET, INFO, or DEBUG. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - QUIET - No messages will be shown. USB Scanner does not echo any information as it runs. However, if an error occurs, then that message will be shown. Also, if the action is TEST or REPORT, and you choose QUIET, then the echo level will be set to INFO. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - INFO - Basic operations are shown. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - DEBUG - Almost every operation is shown, along with current run state. This will produce a large amount of information, but will give you a detailed picture of what the scanner is doing. -------------------------------------------------------------------------------------------- * Scanner Action action = REPORT This is equivalent to the /a: command line switch. You can control which actions the scanner will perform. Possible value are: MODIFY, TEST, and REPORT. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MODIFY - The scanner will scan the serial ports, associate the arduino with the COM port, then will read and modify the binding file. This would be the normal operation action for the scanner. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - TEST - The scanner will perform all its normal actions, except it will not modify the binding file. Instead a separate file will be created which holds the modified Bridge statements. The name of the file is the same as your binding file with the .write extension. If the name of your OpenHAB binding file is: binding.txt, then you will have: binding.txt binding.txt.write You can then manually inspect the two files to verify that the scanner did in fact correctly alter the binding file with the serial port information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - REPORT - The scanner will scan the serial ports and associate each port with its arduino. It will not create any files, but will report which arduino is on which port. You can use this information in other programs, such as the editor (IDE) you are using to program the arduino, so that the correct program goes to the arduino. -------------------------------------------------------------------------------------------- * Serial Port (COM Port) setup This section deals with correctly setting up the communications with the arduino. Each serial port must be set up with the correct settings, otherwise communication is impossible. You would be using the same settings in the binding file, in the Bridge setting. Note that each arduino MUST also use the exact same settings. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - baudRate = 9600 This is the speed of the communication. Possible values are 4800, 9600, 19200, 38400, 57600, or 115200 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - dataBits = 8 The number of bits used for each character. Possible values are 5, 6, 7, or 8 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - parity = N Indicates if a parity bit is used. Possible values are N, O, E, M, or S. Parity is a basic form of cross-checking values for validity. N - None O - Odd E - Even M - Mark S - Space - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - stopBits = 1 The number of bits to use to indicate the end of communications. Possible values are 1, 1.5, or 2. -------------------------------------------------------------------------------------------- * Binding File Name bindingFile = C:\OpenHAB\binding.txt This is the full name of the binding file. You can use either a forward slash or a backslash in the name. USB Scanner will convert the slash to the correct one for the operating system. You can have more than one binding file. Each file will be scanned for Bridge statements and will be modified as required. -------------------------------------------------------------------------------------------- * Listen Time Duration listenTime = 10 This value limits the amount of time (in seconds) the scanner will operate. Normally the scanner will stop searching when all the ports have been identified. But it will keep searching until all the ports have been identified. The listen time keeps the scanner from running forever. After the listen time has expired, the scanner will time out with an error report, and the exit level set to 1. If you see that a port has been found, but that port has not identified itself, try making this value larger to give the arduino more time to respond. Values are 1 to 120 seconds (TWO full minutes!). -------------------------------------------------------------------------------------------- * Arduino Query Delay arduinoDelay = 1000 To give the arduino a chance to fully initialize, the scanner will wait this number of milliseconds before sending out the first identity query request. If this value is larger than the listenTime setting, then the scanner will time out with an error. -------------------------------------------------------------------------------------------- * Arduino Query Text arduinoQuery = who? This is the text sent to each arduino requesting its identity. Each identity MUST be unique. You will have to add the query/reponse code to each arduino. An example of the code is provided in the arduinoCode.c file. You will also have to coordinate the response text for each arduino with both the mapping (below) and the Bridge tag identity, so that the proper Bridge statement is modified. -------------------------------------------------------------------------------------------- * Bridge Arduino Mapping This section explains the mapping of each arduino to its OpenHab Bridge statement. USB Scanner uses the mapping to associate ports with Bridge statements. The mapping section is between Map statements: Map = Start Map = End Every non-blank, non-comment line is assumed to be a mapping statement. The format of the mapping is: = - The response and the Bridge tag can be the same text, if you want. - Both the response and the Bridge tag are case sensitive. - Neither the response nor the Bridge tag can contain spaces or the equals sign. - The response cannot be one of the setting keys. I prefixed the response with IAM: to prevent future key collisions. Map = Start IAM:electronics = electronics IAM:master = masterBedroom Map = End In the above, there are two mappings. USB Scanner will read in the mapping, then query each arduino with the arduinoQuery text. If the response from the arduino matches the arduino response text in the mapping, then that port will be associated with the mapping. Once all the ports have responded and been successfully mapped, USB Scanner will read through the binding file(s) looking for the Bridge mapping tag. The mapping tag is a comment placed immediately before the Bridge statement. USB Scanner looks for this comment, then modifies the Bridge statement with the appropriate SerialPort value; You must place the comment line in the binding file. The comment key //USBScanner must be exactly as shown with no spaces. //USBScanner = electronics Bridge serial:serialBridge:electronics [serialPort="COM4", baudRate=9600] { //USBScanner = masterBedroom Bridge serial:serialBridge:masterBedroom [serialPort="COM1", baudRate=9600] The only parameter USB Scanner will modify is the serialPort. You must ensure that the other Bridge parameters are correct. Please note that USB Scanner reads files one line at a time. Therefore the Bridge statement MUST have the serialPort parameter on the same line as the Bridge statement. The line: Bridge serial:serialBridge:masterBedroom [serialPort="COM1", baudRate=9600] is OK, however: Bridge serial:serialBridge:masterBedroom [ serialPort="COM1", baudRate=9600 ] will fail. ===================================================== There are a number of error conditions, mostly to do with the serial port communications, and setting file values. However the most likely errors will be a mis-configuration between the arduino response text, the setting file mapping, and the binding file Bridge identity tags. All the mappings MUST be used. If a mapping does not exist, then the assumption is that the arduino is not working, not attached, or is reporting a bad identity. Therefore the scanner will stop with an error. Only if ALL the conditions have been satisfied will the binding file be modified. Enjoy!