Documentation

Author: fransjacobs

DRIVING.md

@@ -0,0 +1,62 @@
+# Driving with JCS
+
+- Manual
+- Automatically
+
+## Manual
+
+For Manual Driving Loc Driver Cab Dialog is avaliable. This this Dialog a Locomotive can be controlled. Functions can be switched. Multipel dialog can be show simultanously.
+The Locomotive Driver can be opened by double clicking on the locomotive of choice in locomotive list.
+
+![LOCOMOTIVE_LIST](assets/locomotive-list.png)
+
+### Driver Cab
+
+![DRIVER_CAB](assets/drivercab-dialog.png)
+
+### Accessory Switching
+
+Click in the toolbar on the "switch" button to show Accessory Keyboard
+
+![ACCESSORY_KEYBOARD](assets/accessory-keyboard.png)
+
+The Accessory buttons directly switch the address as shown on the Button.
+
+## Automatic Driving
+
+In the Home Screen click on a Block to set a locomotive in a Block. The first step is to place a locomotive on the track, both pysical as grapical ;)
+
+![LOC_ASSIGNMENT](assets/blockproperties-assignment.png)
+
+For each block the wait times can be set.
+
+![BLOCK_WAITING](assets/blockproperties-waittimes.png)
+
+When the __Always Stop__ checkbox is checked, a locomotive will stop and wait for the specified waiting time be for starting a new cycle. The Min. Wait Time is used in case the __Random Wait__ is not selected.
+
+When the __Random Wait__ checkbox is checked a random time between the min and max wait time is used when a locomtive stops in the block.
+
+![LOC_IN_BLOCK](assets/loc-in-block-1.png)
+
+When this pysical direction of the locomotive is different, it can be changed by either using:
+
+- Reverse Arrival side
+- Toggle Direction
+
+By Right clicking on the block these menu options are available.
+
+![LOC_IN_BLOCK](assets/right-click-block-menu.png)
+
+## Start Auto Pilot
+
+The JCS AutoPilot is the automatic driving Algorithm within JCS.
+AutoPilot is enabled by clicking the __*Pilot*__ button.
+Every locomotive on track is assigned a Dispatcher. whic can be viewd in the Dispatcher List.
+
+![LOC_IN_BLOCK](assets/autopilot-dispatcher.png)
+
+A Locomotive can by started by right click via the Block Menu or Start All by clicking on the __Cruise Control__ button.
+
+When Auto drive start the Status of the dispatche is shown in the Dispatche list. Also the layou screen will show what is happening by shoing reserved routes and Block States.
+
+![LOC_DRIVING](assets/loc_driving.png)

JCS_SETUP.md

@@ -3,12 +3,13 @@
 ***
 
 ## Get Started driving your Trains automatically
+
 This guide explains how to configure JCS for a layout and automatically run trains.
 For the purpose of this guide the following Layout is used.
 ![Test Layout](assets/testlayout.png)
 
 This layout consist out of 4 blocks and 2 switches.
-Every block has 2 sensors, in total there are 8 sensors used. 
+Every block has 2 sensors, in total there are 8 sensors used.
 What is a Block? A block is a part of track where one train can be without hindering other routes. In JCS a block is always demarcated by two sensors.
 
 ## Drawing the Layout
@@ -24,13 +25,20 @@ Use the __+__ button to add a tile on the canvas. The Bin button will delete a t
 Rightclick on a tile to see properties or rotate or flip if applicable.
 When a tile is selected it can be dragged to the right position. Tiles are automatically saved. The example looks like this when all tiles are placed on the canvas.
 
-![Start Edit](assets/layoutedit1.png?raw=true)
+![Start Edit](assets/layoutedit1.png)
+
+## Pysical vs schematic Layout
 
-## Configuring Accessories and Sensors
+The below picure shows the physical layout side by side with the schematic layout.
+![LAYOUT_OVERVIEW](assets/TestLayoutSideBySide.png?raw=true)
+
+### Configuring Accessories and Sensors
 
 The next step is to configure the Accessories and Sensors.
-Accessories Sensore and locomotive are alway linked to a Command Station.
+Accessories, Sensors and Locomotives are always linked to a Command Station.
+
 #### Step 1 selecting the Default Command Station
+
 For this guide the [DCC-EX](https://dcc-ex.com) Command Station is used. Feedback via [DCC-EX](https://dcc-ex.com) is not yet supported, see [issue 59](https://github.com/fransjacobs/model-railway/issues/59), hence the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) is used for Sensor feedback.
 Use the cog button or via Menu -> Tools Command Stations to show the Command Station Dialog.
 
@@ -43,17 +51,20 @@ Set the [DCC-EX](https://dcc-ex.com) Command Station as __Default__ and __Enable
 The Test Button can be used to check whether the connection can be established.
 
 ##### Setup the Feedback module(s)
+
 In the Command Station Dialog select the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) in the Command Stations dropdown menu.
 
-![Setup HSI-S88](assets/command-station-HSI-S88.png) 
+![Setup HSI-S88](assets/command-station-HSI-S88.png)
 
-Do __*NOT*__ set the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) as *Default*, as the default Command Station is supposed to put the power on the Track. However set the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) __Enabled__.
+Do __*NOT*__ set the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) as *Default*, as the default Command Station is supposed to put the power on the Track.
+However set the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) __Enabled__. The [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) is connected via the "ttyACM1" port.
 
 For the Feedback Interface like the [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) the number of connected S88 modules has to be specified. Set the Channel to which the S88 module(s) is/are connected and the number of Modules.
 In this case one S88 module, connected to Channel 0 is used.
 Click on __*Re-create Sensors*__ button to create the sensors in the system.
 
-### Step 2 create Accessories 
+### Step 2 create Accessories
+
 The Test track has two turnouts which can be added using the Accessory Dialog. This Dialog can be opened via Settings (Mac) or Menu -> Tools -> Options.
 To Add a new Accessory click on the __+__ button. For a Turnout choose the right Turnout type in the __*Type*__ dropdown menu.
 
@@ -62,11 +73,12 @@ To Add a new Accessory click on the __+__ button. For a Turnout choose the right
 To save the Accessory click the Save Button. When save the Accessory will appear in the list on the left side. This List can be filtered using the 3 radio buttons on top (All, Turnouts, Signals).
 
 ### Step 3 add Locomotives
+
 As we are in the options Dialog let's also add the Locomotives. In this Example two locomotives used. For both locomotives an icon is already put in a subdirectory .../jcs/images.
 
 ![Edit Locomotive](assets/locomotive-edit.png)
 
-Locomotives can only commute back and forth, hence the __Commuter__ check box is selected for both locomotives. If the __Commuter__ checkbox not selected the Locomotice can __*NOT*__ change direction in Automatic mode. 
+Locomotives can only commute back and forth, hence the __Commuter__ check box is selected for both locomotives. If the __Commuter__ checkbox not selected the Locomotice can __*NOT*__ change direction in Automatic mode.
 
 ### Step 4 Link sensors to their graphical representation
 
@@ -90,22 +102,35 @@ The Sensor Monitor will appear. When the sensor is activated (pre condition is t
 
 Select the Sensor with the right name in Sensor Properties dialog. Repeat this for all sensors in the layout.
 
-### Step 5 Trace the layout
+### Step 5 Link Accessories to the pycisl ones
+
+Like the Sensor also accessories __must__ be linke to their pysical counterpart.
+Right click on the Accessory and select properties.
+
+![LINK_ACCESSORY](assets/link_accessory.png)
+
+### Step 6 Trace the layout
+
 Trace the layout. This will generate all the driveways from block to block. Click on the __*Trace*__ button.
 
-![Show Routes](assets/routes-dialog-empty.png) 
+![Show Routes](assets/routes-dialog-empty.png)
 
 Left of the Main JCS Window the Routes Dialog will Appear.
 Click in the __*Trace*__ Button in the *Routes Dialog* to generate all possible routes.
 
-![Empty Routes](assets/routes-dialog-traced.png) 
+![Empty Routes](assets/routes-dialog-traced.png)
 
 When a route is selected in the list it is displayed in the main screen.
 
-### Step 6 Configure the Blocks
-Configure the Block properties.
-First Restart JCS. This is due to a [known issue 78](https://github.com/fransjacobs/model-railway/issues/78).
+### Step 7 Configure the Blocks
+
+Configure the Block properties. For every Block a name __must__ be filled in. Sensors must be linked to a block. The side of the Block with the __Bold__ line is the __+__ (plus) side of the Block. The Sensors can be automatically linked by using the __*Auto Link*__ Button.
+Notice: when the Sensors do not link to the block, the sensors are usually not linked to a pysical sensor.
+
+![Empty Routes](assets/block-properties.png)
+
+After all these settings are done a restart of JCS is strongly advised.
 
- The Sensors must be linked to a block. The side of the Block with the __Bold__ line is the __+__ (plus) side of the Block. The Sensor can be automatically linked.
+## Driving
 
-TBW
+[DRIVING](DRIVING.md)

README.md

@@ -9,9 +9,12 @@
 ![GitHub issues](https://img.shields.io/github/issues-raw/fransjacobs/model-railway)
 ![GitHub Release](https://img.shields.io/github/v/release/fransjacobs/model-railway)
 ***
-## About The Project
-JCS is a hobby project of me where I try to automate my Model Railway. The past year I have on and off worked on several aspects or modules of the software whic are needed to finally drive automatically. A short summary of the topics which are needed and used to finally be able to drive a train automatically:
-- Connectivety to the Command Station hardware. (DCC-EX,HSI-S88, Marklin CS2/3)
+## About the Project
+
+JCS is a hobby project of me where I try to automate my Model Railway. Over the past years I have worked on and off on several aspects and modules of the software which are needed to drive automatically.
+A short summary of the topics which are needed and used to be able to drive trains automatically:
+
+- Connectivity to the Command Station hardware. (DCC-EX,HSI-S88, Marklin CS2/3)
 - Edit and display graphically a layout
 - With the layout be able to route all the possible drive ways
 - Show the routes and driveways in the layout screen
@@ -24,6 +27,7 @@ JCS is a hobby project of me where I try to automate my Model Railway. The past
 I created a [short video](https://youtu.be/xP6eUdScMY0) demonstrating automatic running of locomotives. Also a [video of pysical locomotives running on the Test Layout](https://www.youtube.com/watch?v=CyLmGk6gfHA)
 
 ## Why?
+
 There are already many "out of the box" working products. I wanted to create my own to learn and to have FUN!
 
 As I am a great supporter of Open Source I have put the project on github with the purpose for others to use it, learn from it, or improve it.  
@@ -32,15 +36,24 @@ So I hope you get inspired!
 
 Frans
 
+## Guides
+
+- Setup : [JCS_SETUP](JCS_SETUP.md)
+- Driving : [DRIVING](DRIVING.md)
+
 ## Screenshots
+
 So here are a few screenshots of the Project:
-#### Thottle / Driver Cab
+
+### Thottle / Driver Cab
+
 The Locomotive- and function images are displayed. Images are automatically downloaded from the Central Station.
 Or can be manually added.
 
 ![UI screenshot: JCS Throttle](assets/driver_cab.png?raw=true)
 
-#### Layout overview
+### Layout overview
+
 The (schematic) layout is displayed. Locomotive can be Placed in a Block.
 When the AutoPilot is switched on Locomotive will drive from block to block.
 ![UI screenshot: JCS Main Screen](assets/mainscreen.png?raw=true)
@@ -49,44 +62,48 @@ In Editmode you can draw a layout using pre defined Tiles.
 also the layout can be routed. (it the very first and early step for the preparation of automatic running).
 ![UI screenshot: JCS Edit Screen](assets/mainscreen_edit_route.png?raw=true)
 
-#### Sensor Monitor
+### Sensor Monitor
+
 To debug or easly setup your feedback sensors 
 ![UI screenshot: JCS Sensor Monitor](assets/sensor_monitor.png?raw=true)
 
-#### Keyboard Panel for switching accessories and viewing feedback sensor status
+### Keyboard Panel for switching accessories and viewing feedback sensor status
 
 ![UI screenshot: JCS keyboard Screen](assets/keyboard-panel.png?raw=true)
 
-#### Import Locomotives from a CS-2 or CS-3
+### Import Locomotives from a CS-2 or CS-3
+
 ![UI screenshot: JCS Preferences Locomotives](assets/prefs_locomotives.png?raw=true)
 
 ## Releases
-* [First Release V 0.0.1](https://github.com/fransjacobs/model-railway/releases/tag/V0.0.1)
+
+- [First Release V 0.0.1](https://github.com/fransjacobs/model-railway/releases/tag/V0.0.1)
 
 ## Supported Hardware
-* [DCC-EX](https://dcc-ex.com) can be connected either via serial port or network
-* [Marklin CS-2](https://www.marklin.nl/producten/details/article/60215)
-* [Marklin CS-3](https://www.marklin.nl/producten/details/article/60216)
-* [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) or the [DIY version](https://mobatron.4lima.de/2020/05/s88-scanner-mit-arduino) for feedback
+
+- [DCC-EX](https://dcc-ex.com) can be connected either via serial port or network
+- [Marklin CS-2](https://www.marklin.nl/producten/details/article/60215)
+- [Marklin CS-3](https://www.marklin.nl/producten/details/article/60216)
+- [HSI-S88](https://www.ldt-infocenter.com/dokuwiki/doku.php?id=en:hsi-88-usb) or the [DIY version](https://mobatron.4lima.de/2020/05/s88-scanner-mit-arduino) for feedback
 
 ## Current status
+
 Currently the following feature are in development:
-* Internationalization enable multiple languages
-* Add support for ESU ECOS
-* Show Signal aspects in automatic driving
-* Document
-
-## TODO's (and there are still a lots of todo's...):
-Currently the following features are under active development:
-* Documentation
-* Enhance GUI
-* Add more Unit tests
-* ...
+
+- Documentation
+- Internationalization enable multiple languages
+- Add support for ESU ECOS
+- Show Signal aspects in automatic driving
+- Enhance GUI
+- Add more Unit tests
+- ...
 
 ## License
+
 [LICENSE](LICENSE.md)
 
 ## Build JCS from source
+
 [BUILDING](BUILDING.md)
 
 ## Contributors
@@ -105,7 +122,7 @@ Currently the following features are under active development:
 </tr>
 </table>
 
-** Copyright 2019 - 2024 Frans Jacobs **
+## Copyright 2019 - 2024 Frans Jacobs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,

assets/accessory-keyboard.png

@@ -366,11 +366,16 @@ private void saveExitBtnActionPerformed(java.awt.event.ActionEvent evt) {//GEN-F
           //Can't be null and should be the same as the block
           bb.setId(this.block.getId());
         }
-        
-        if(bb.getStatus() == null) {
+
+        if (bb.getStatus() == null) {
           bb.setBlockState(BlockBean.BlockState.FREE);
         }
-        
+
+        if (bb.getMinWaitTime() == null) {
+          //The wait time cannot be null, put a default there
+          Integer minWait = Integer.getInteger("default.min.waittime", 10);
+          bb.setMinWaitTime(minWait);
+        }
 
         PersistenceFactory.getService().persist(bb);
       }