SXL 1.2.1

.github/workflows/gh-pages.yml

@@ -0,0 +1,132 @@
+# This workflow updates the sphinx documentation and builds a website
+
+name: Build SXL TLC
+
+on:
+  push:
+    branches: [ 1.2.1 ]
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  build-sxl-tlc:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out rsmp_sxl_traffic_lights repository (gh-pages)
+      uses: actions/checkout@v4
+      with:
+        ref: gh-pages
+    - name: Check out rsmp_sxl_traffic_lights repository (1.2.1 branch)
+      uses: actions/checkout@v4
+      with:
+        path: 1.2.1
+        ref: 1.2.1
+    - name: Check out rsmp_schema repository
+      uses: actions/checkout@v4
+      with:
+        repository: rsmp-nordic/rsmp_schema
+        path: rsmp_schema
+    - name: Check out sxl-tools repository
+      uses: actions/checkout@v4
+      with:
+        repository: rsmp-nordic/sxl-tools
+        path: sxl-tools
+    - name: Create ReStrucTured text (RST) from yaml
+      run: |-
+        sudo apt-get -y install python3-tabulate python3-pypandoc
+        sxl-tools/yaml2rst.py <rsmp_schema/schemas/tlc/1.2.1/sxl.yaml >1.2.1/source/sxl_traffic_light_controller.rst
+    - name: Install dependencies
+      run: |
+        sudo add-apt-repository ppa:inkscape.dev/stable
+        sudo apt-get update
+        sudo apt-get -y install \
+              python3-sphinx \
+              python3-sphinx-rtd-theme \
+              texlive \
+              texlive-latex-extra \
+              texlive-humanities \
+              texlive-fonts-extra \
+              imagemagick \
+              inkscape \
+              librsvg2-bin \
+              latexmk \
+              mscgen
+    - name: Build rsmp_sxl_traffic_lights repository
+      run: |
+        cd 1.2.1
+        make html latexpdf
+    - name: Setup git
+      run: |
+        git config --local user.email "[email protected]"
+        git config --local user.name "GitHub Action"
+    - name: Commit documentation changes
+      run: |
+        mkdir -p docs/1.2.1
+        cp -r 1.2.1/build/html/* docs/1.2.1
+        git pull -q
+        git add docs/1.2.1
+        git commit -m "Update documentation" -a || true
+        # The above will fail if no changes were present, so
+        # we ignore the return code.
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+    - name: Upload PDF as artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: PDF
+        path: 1.2.1/build/latex/sxl-tlc.pdf
+
+  build-sxl-excel-tlc:
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Check out rsmp_schema repository
+      uses: actions/checkout@v4
+      with:
+        repository: rsmp-nordic/rsmp_schema
+        path: rsmp_schema
+    - name: Check out sxl-tools repository
+      uses: actions/checkout@v4
+      with:
+        repository: rsmp-nordic/sxl-tools
+        path: sxl-tools
+
+    - name: Install dependencies
+      run: |-
+        gem install rubyXL --user
+        sudo apt install python3-xlsxwriter
+
+    - name: Create xlsx template
+      run: |
+        sxl-tools/create_template.py \
+          --num-grouped-objects 5 \
+          --num-single-objects 510 \
+          --num-alarms 26 \
+          --num-statuses 54 \
+          --num-command-functional-position 1 \
+          --num-command-functional-state 1 \
+          --num-command-maneuver 1 \
+          --num-command-parameters 24 \
+          --alarm-rvs 5 \
+          --status-rvs 10 \
+          --command-args 7 \
+          --output template.xlsx
+
+    - name: Export to xlsx
+      run: |
+        sxl-tools/yaml2xlsx.rb \
+          --template template.xlsx \
+          --stdout \
+          --short-desc \
+          --sxl rsmp_schema/schemas/tlc/1.2.1/sxl.yaml \
+          --site sxl-tools/tlc/SXL_Traffic_Controller_ver_1_1-site.yaml \
+          > SXL_Traffic_Controller_ver_1_2_1.xlsx
+
+    - name: Upload Excel as artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: Excel
+        path: SXL_Traffic_Controller_ver_1_2_1.xlsx

Readme.md

@@ -21,9 +21,10 @@ Including:
 - Chapter 8: Examples of all alarms, statuses and commands:
 - Chapter 9: Change log
 
-## FAQ
+## Wiki
 
-Please see the [faq](faq.md) for frequently asked questions.
+Please see the SXL for TLC [Wiki](https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights/wiki)
+for best practices and frequently asked questions.
 
 ## Generating the specification from source
 

source/changelog.rst

@@ -4,6 +4,19 @@
 Change log
 ==========
 
+Version 1.2.1
+-------------
+Release date: 2024-06-25
+
+The full list of changes between 1.2.1 and 1.2 can be viewed on github.
+:compare:`v1.2...v1.2.1`
+
+- Add "start-up interval" to the definitions. :issue:`184`
+- Clarification of string format in S0002, S0003, S0004, S0012, S0029, S0030. :issue:`166`
+- Clarification of M0001 (normal/yellow flash/dark mode). :issue:`160`
+- Clarification of S0020 (control mode). :issue:`139`
+- Deprecation of M0004 (restart). :schema_issue:`99`
+
 Version 1.2
 -----------
 Release date: 2023-10-03

source/conf.py

@@ -58,17 +58,17 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.2'
+version = '1.2.1'
 # The full version, including alpha/beta/rc tags.
-release = '1.2'
-today = 'Oct 03, 2023'
+release = '1.2.1'
+today = 'Jun 01, 2024'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -83,10 +83,12 @@
 
 # Github issues
 
-extlinks = {'issue': ('https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights/issues/%s', '[%s]'),
-            'pull': ('https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights/pulls/%s', '[%s]')}
-
-
+extlinks = {
+    'issue': ('https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights/issues/%s', '[%s]'),
+    'schema_issue': ('https://github.com/rsmp-nordic/rsmp_schema/issues/%s', '[%s]'),
+    'pull': ('https://github.com/rsmp-nordic/rsmp_sxl_traffic_lights/pulls/%s', '[%s]'),
+    'compare': ('https://github.com/rsmp-nordic/rsmp_core/compare/%s', '[%s]')
+}
 
 # -- Options for HTML output ----------------------------------------------
 

source/coordination.rst

@@ -155,7 +155,7 @@ the following general requirements:
 - The TLC must be able to communicate with the supervision system at the
   same as communicating between TLC:s.
 
-..  _4.3 Transport of data:  https://rsmp-nordic.org/rsmp_specifications/core/3.2/applicability/transport_of_data.html
+..  _4.3 Transport of data:  https://rsmp-nordic.github.io/rsmp_specifications/core/3.2.1/applicability/transport_of_data.html
 
 Functional requirements of the TLC
 ----------------------------------
@@ -272,7 +272,7 @@ Initialization sequence for local coordination
    terminated if it turns false in any follower.
 7. Leader sends START/STOP order using M0006 or M0013 to followers
    during each cycle.
-8. Leader receives START/STOP order using output (M0004) from followers
+8. Leader receives START/STOP order using output (S0004) from followers
    during each cycle.
 
 .. figure:: /img/msc/local_coordination.png
@@ -303,7 +303,7 @@ Initialization sequence for coordination with synchronized cycle counter
 6. If external control bits are used: Leader sends START/STOP order to
    followers during each cycle
 7. If external control bits are used: Leader receives START/STOP order
-   using output (M0004) from followers during each cycle.
+   using output (S0004) from followers during each cycle.
 
 .. figure:: /img/msc/central_coordination.png
    :align: center

source/definitions.rst

@@ -93,3 +93,7 @@ The corresponding ASCII character used for signal group status (S0001) is writte
       with the fixed time whereby it must be longer to have any effect.
       (R function)
 
+   Start-up interval
+     The controller always starts with a start-up sequence for the signal groups before using normal 3-light control.
+     The general definition of the signal group status for each interval can be found in the :ref:`signal-group-status`,
+     but the exact definition depends on national regulations, including the duration of each interval of the sequence.

source/examples.rst

@@ -42,7 +42,6 @@ This document contains examples for all message types.
 + `S0015 Current traffic situation`_
 + `S0016 Number of detector logics`_
 + `S0017 Number of signal groups`_
-+ `S0018 Number of time plans`_
 + `S0019 Number of traffic situations`_
 + `S0020 Control mode`_
 + `S0021 Manually set detector logic`_

source/multiple_supervisors.rst

@@ -11,4 +11,4 @@ For example, a traffic light controller might connect to both a traffic
 management system and a bus priority system. Or it might connect to both a
 traffic management system and a secondary monitoring system.
 
-.. _4.3.1 Multiple supervisors: https://rsmp-nordic.org/rsmp_specifications/core/3.2/applicability/transport_of_data.html#multiple-supervisors
+.. _4.3.1 Multiple supervisors: https://rsmp-nordic.github.io/rsmp_specifications/core/3.2.1/applicability/transport_of_data.html#multiple-supervisors

source/signal_group_status.rst

@@ -1,3 +1,5 @@
+.. _signal-group-status:
+
 Signal Group status
 ===================
 
@@ -15,9 +17,9 @@ Each character has the following definition:
    b     Manual control to dark                            Dark
    c     Manual control to flashing yellow                 Yellow flash
    d     Manual control to flashing red                    Red flash
-   e     Start-up interval 1                               Dark or yellow flash
-   f     Start-up interval 2                               Vehicles: yellow, Pedestrians: red
-   g     Start-up interval 3                               Red
+   e     :term:`Start-up interval` 1                       Dark or yellow flash
+   f     :term:`Start-up interval` 2                       Vehicles: yellow, Pedestrians: red
+   g     :term:`Start-up interval` 3                       Red
    h     Manual control to red                             Red
    A     :term:`Red rest without start order`              Red                                N
    B     :term:`Red rest`                                  Red                                N