LocoNet over TCP - LbServer Version 1 - User Manual

LocoNet over TCP - LbServer Version 1 - User Manual

This is the User’s Manual of the Version 1 (1.N) of LocoBuffer Server “LbServer”.

The Developer manual is here.

Installation

Requirements

To successfully install and run LbServer1 you will need to install a Java Runtime (JRE) of Version 1.7 or later. We recommend to install the Oracle version but OpenJDK has also been used with success.

When jSSC (java-simple-serial-connector) is used as serial driver it must support your operation system. jSSC (current version 2.8.0) supports Windows(x86, x86–64), Linux(x86, x86–64, ARM soft & hard float), Solaris(x86, x86–64) and Mac OS X(x86, x86–64, PPC, PPC64).

When using a hardware interface that connects through USB you also will need a device driver for your interface. On Windows you will usually have to install it before. On most Linux distributions the device driver is supplied with your distributions and not additional installation is required.

Installation on Unix

This installation procedure should work on different Linux distributions and other Unix based platforms, but we can not test all platforms. This instructions have been tested on ubuntu version 16.04. Some specific hints about Raspbian can be found here.

First validate that Java is properly installed. In a terminal type java -version. The output should show the current version:

$ java -version
java version "1.7.0_80"
Java(TM) SE Runtime Environment (build 1.7.0_80-b15)
Java HotSpot(TM) 64-Bit Server VM (build 24.80-b11, mixed mode)
$

On most Linux system you can switch the used runtime with sudo update-alternatives --config java.

Download latest lbserver1_1.NN.run from https://sourceforge.net/projects/loconetovertcp/files/LbServer1/ and save as file. Open a terminal and execute:

$ sudo sh lbserver1_1.NN.run
Verifying archive integrity... All good.
Uncompressing LbServer 1.NN from LocoNet over TCP Project  100%  
make directory /opt/lbserver1
copy files to /opt/lbserver1
setting owner and access mode
create logging directory /var/log/lbserver1
create links 'lbserver' and 'lbservercfg' in /usr/local/bin
$

Now you should create a configuration for your system. On systems without X11 you can manually copy and edit the file:

$ sudo cp /opt/lbserver1/LbServer.properties /etc/opt/lbserver1/
$ sudo vi /etc/opt/lbserver1/LbServer.properties

Follow the comments in the file. One valid set for LocoBuffer-USB could be:

INTERFACE = /opt/lbserver1/LocoBuffer_USB.interface
net.sf.loconetovertcp.LbServer.port = 1234
net.sf.loconetovertcp.LbServer.host =
net.sf.loconetovertcp.driver.device = /dev/ttyUSB0
#net.sf.loconetovertcp.driver.JsscDriver.send_timestamps = true
#net.sf.loconetovertcp.driver.JsscDriver.disable_send = false

If you can start an X11 application you should start LbServerCfg by:

$ sudo lbservercfg

Change settings, press Save and exit with Exit. To update the list of devices after plugging in new interfaces press Update Devices.

Installation on Windows

To validate that java is installed open cmd.exe and type java -version:

Download latest lbserver1_1.NN_Win32_Setup.zip from https://sourceforge.net/projects/loconetovertcp/files/LbServer1/ and save as file. Unzipping this file will create a directory lbserver1_1.NN_Win32_Setup. Navigate to this directory and execute setup.exe. Accept the default path C:\Program Files (x86)\LoconetOverTcp.sf.net\LbServer1\` (orC:\Program Files\LoconetOverTcp.sf.net\LbServer1` on 32 bit systems) and proceed through all screens.

Start LbServerCfg from Menu:
Start >> All Programs >> LocoNet over TCP >> LbServer 1 - configure

Change settings, press Save and exit with Exit. To update the list of devices after plugging in new interfaces press Update Devices.

Running

Running on Unix

Open a new terminal and start LbServer:

$ lbserver
LbServer [1.NN]  ?? 2015, 2016 by Stefan Bormann and Martin Pischky
This is a LoconetOverTcp server for several Loconet interfaces.
Reading configuration /etc/opt/lbserver1/LbServer.properties
Opening driver...
(  334) JsscDriver - open(): Opened port /dev/ttyUSB0 with 57600bps
Starting server...
server is now STARTING
Server started. Press ENTER to terminate.
server is now RUNNING

Running on Windows

Start LbServer
Start >> All Programs >> LocoNet over TCP >> LbServer 1 - start

Configuration

Configuration on Unix

Configuration of LbServer is done by configuration files and options/arguments passed on the command line.

The files used on Unix are:

/etc/opt/lbserver1/LbServer.properties
/opt/lbserver1/LbServer.properties
/opt/lbserver1/*.interface

The primary configuration is stored in a file /etc/opt/lbserver1/LbServer.properties. If this files does not exist, the file LbServer.properties in the installation directory (/opt/lbserver1) is read. LbServerCfg only modifies the first file but may use the second as a template when you press Save and the first does not exist.

The configuration files usually loads the definitions for the hardware interface by including another file with the INTERFACE property (E.g.: INTERFACE = /opt/lbserver1/LocoBuffer_USB.interface). In LbServerCfg this file is determined by the selection in the first combobox. The list of possible values is found by scanning for all existing *.interface files.

If you need more control over the options you can create a custom configuration by creating a properties files (e.g.: myconfig.properties) and start LbServer by lbserver -c myconfig.properties. The format is described on the Apache Commons Configuration website in the documentation in the User Guide (search for PropertiesConfiguration).

You can also pass arguments on the command line. To get info about the possible options and arguments start lbserver --help:

$ lbserver --help
LbServer [1.NN]  ?? 2015, 2016 by Stefan Bormann and Martin Pischky
This is a LoconetOverTcp server for several Loconet interfaces.
Reading configuration /etc/opt/lbserver1/LbServer.properties

usage: lbserver [<options>] [<port>] [<driver>]
 -b,--baud <baud>    serial baudrate to use
 -c,--config <arg>   the configuration to use
 -d,--device <arg>   the name of the serial device
 -h,--help           print help message
 port                TCP port number for LoconetOverTcp-server. Defaults to
                     1234.
 driver              The device driver for access of the interface hardware.
                     This may be a name from the list below. Alternatively
                     this may be the name of a class that implements 
                     net.sf.loconetovertcp.driver.Driver and is located
                     somewhere in the class path. Defaults to
                     Jssc.

List of drivers included:
   SERIALDRIVER  Short description of SerialDriver
           JSSC  A serial driver using jSSC (java-simple-serial-connector)
          DUMMY  Simple loopback server without physical connection to LocoNet

For detailed help with one driver and its args:
lbserver --help <driver>
$

Options or arguments passed on the command line override options read from the files. If you (for example) want to use a different device just start by lbserver -d /dev/ttyACM0.

Configuration on Windows

Configuration on Windows is similar to Unix. Please see Configuration on Unix. The files used on Windows are:

C:\ProgramData\LoconetOverTcp.sf.net\LbServer1\LbServer.properties
C:\Program Files (x86)\LoconetOverTcp.sf.net\LbServer1\LbServer.properties
C:\Program Files (x86)\LoconetOverTcp.sf.net\LbServer1\*.interface

Logging

TODO: a new logfile for every day.

Unix:

/var/log/lbserver1/lbserver.log

Windows:

C:\ProgramData\LoconetOverTcp.sf.net\LbServer1\logs\lbserver.log

Uninstall

Uninstall on Unix

Start the uninstall.sh in the installation directory. The configuration file is not removed. You can keep it for later installations or delete it manually.

$ sudo sh /opt/lbserver1/uninstall.sh 
remove links 'lbserver' and 'lbservercfg' in /usr/local/bin
remove files in /opt/lbserver1
remove directory /opt/lbserver1
remove log files in /var/log/lbserver1
Configuration in '/etc/opt/lbserver1/LbServer.properties' not removed
$
$ sudo rm /etc/opt/lbserver1/LbServer.properties
$

Uninstall on Windows

Use the system configuration:

Start >> System Configuration >> Remove Programs

Search for LbServer1 and remove.