Merge pull request #34 from Peter-van-Tol/11-add-external-extensions-…

…to-litexcnc

11 add external extensions to litexcnc

.devcontainer/devcontainer.json

@@ -38,5 +38,5 @@
 	// "postCreateCommand": "pip install --user -r requirements.txt",
 
 	// Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
-	// "remoteUser": "vscode"
+	"remoteUser": "vscode"
 }

.devcontainer/docker-compose.yml

@@ -18,7 +18,7 @@ services:
     command: sleep infinity
 
     # Uncomment the next line to use a non-root user for all processes.
-    # user: vscode
+    user: vscode
 
     # Use "forwardPorts" in **devcontainer.json** to forward an app port locally.
     # (Adding the "ports" property to this file will not forward from a Codespace.)

CHANGELOG.rst

@@ -6,17 +6,32 @@ All versions in this changelog have two entries: ``dirver`` and ``firmware``. Th
 have the same version, as communication protocol might change between versions. In the firmware/driver there
 is a safeguard to prevent miscommunication.
 
-Version 0.9.0-alpha1
-====================
+Version 1.0.0
+=============
 
-This is a test version for release to PyPi. 
+First release!
 
 * ``driver``:
 
-  * Main driver with supported modules: ``GPIO``, ``PWM``, ``StepGen``
-  * Ethernet/Etherbone driver
+  * Modules and boards can be extended with plugins. The available modules and boards are automatically picked up
+    by the script ``litexcnc install_driver``.
+  * Removed dependency on JSON-libraries. The configuration is now announced from the FPGA at initialisation
+  * Main driver with supported modules: ``gpio``, ``pwm``, ``stepgen``, ``encoder``;
+  * Ethernet/Etherbone driver;
 
 * ``firmware``:
 
-  * Supported modules: ``GPIO``, ``PWM``, ``StepGen``
+  * Modules can be extended with plugins, this requires a different approach in the configuration JSON. The configs 
+    created for version 0.9 will not work in this version without modification.
+  * Firmware contains configuration.
+  * Supported modules: ``gpio``, ``pwm``, ``stepgen``, ``encoder``;
   * Supported cards: ``5A-75B``, ``5A-75E``
+
+
+Previous test-releases
+======================
+
+Several test releases have been made with increasing functionality and several bug-fixes. These versions have
+now been superseeded by the v1.0-releases of Litex-CNC. These pre-releases differ significantly in setup and 
+design philosophy from the v1.0-release as they were monolythic and difficult to expand with new modules. They
+have served the purpose to remove bugs in the algorithms of the various modules.

README.md

@@ -7,9 +7,6 @@ This project aims to make a generic CNC firmware and driver for FPGA cards which
 
 The idea of this project was conceived by ColorCNC by *romanetz* on the official LinuxCNC and the difficulty to obtain a MESA card.
 
-> **Work in progress** <br>
-> The basic functions GPIO, PWM, Stepgen and encoders are working. Expansion of the project with encoders, I2C, RS489, etc. is now required to allow for more flexibility (for example: sending commands to a HY VFD).
-
 ## Acknowledgements
 This project would not be possible without:
 - ColorCNC by *romanetz* [link](https://forum.linuxcnc.org/27-driver-boards/44422-colorcnc?start=0);
@@ -24,89 +21,12 @@ pip install --extra-index-url https://test.pypi.org/simple/ litexcnc[cli]
 > **NOTE: Suffix `[cli]` required!** <br>
 > The suffix `[cli]` is required to install the command-line interface. Without this suffix the scripts referenced below will not work.
 
-After installation of LitexCNC, one can setup building environment for the firmware and its driver using the included scripts:
+After installation of LitexCNC the following scripts are available to the user:
 ```shell
 litexcnc install_driver
 litexcnc install_litex
 litexcnc install_toolchain
+litexcnc build_driver
 ```
 
-> **NOTE: Python script not on path** <br>
-> In some cases the scripts cannot be found, one of the causes might be that the scripts folder is not on the system path or in case multiple Python installations are present on the system. In these case the scripts can be used with `python -m litexcnc <command>`. It might be necessary to replace `python` with `python3` or the name of the python executable in which litexcnc is installed.
-
-Both Litex and the toolchain (OSS-CAD-suite) will be installed by default be installed in the `/opt` folder. Optionally the flag `--user` can be supplied to both commands, in which case the building environment is installed in `HOME`-directory.
-
-## Configuration of the FPGA
-
-### Structure of the JSON file
-...
-
-### Building the firmware (bit-file)
-The firmare can be created based with the following command:
-```shell
-litexcnc build_firmware "<path-to-your-configuration>" --build 
-```
-
-### Compiling the driver
-
-> Compilation of the driver is only required once as long the same version of LitexCNC is used. When LitexCNC is updated, please re-install the driver; the version of the firmware should always be the same as the version of the driver. 
-
-The firmare can be created based with the following command:
-```shell
-litexcnc install_driver
-```
-
-This script will run `apt-get` to install the following packages:
-- `libjson-c-dev`, which is required to read the configuration files. 
-- `linuxcnc-dev`, which is required for running `halcompile`.
-
-After this, the driver is installed using `halcompile`.
-
-## Usage in HAL
-Typically main litexcnc driver is loaded first:
-```
-loadrt litexcnc
-```
-
-After loading the main driver, the board-driver can be loaded. At this moment only ethernet cards are supported using the `litexcnc_eth` board-driver. All the board-driver modules accept a load-time modparam of type string array, named `config_file`. This array has one config_file string for each board the driver should use. Each json-file is passed to and parsed by the litexcnc driver when the board-driver registers the board. The paths can contain spaces, so it is usually a good idea to wrap the whole thing in double-quotes (the " character). The comma character (,) separates members of the config array from each other.
-```
-loadrt litexcnc_eth config_file="/workspace/examples/5a-75e.json"
-```
-
-### Functions
-
-The table below gives the functions exported by LiteX-CNC. 
-
-| Function        | Description |
-|-----------------|-------------|
-| litexcnc_<BoardName>.<BoardNum>.read | This reads the encoder counters, stepgen feedbacks, and GPIO input pins from the FPGA. |
-| litexcnc_<BoardName>.<BoardNum>.write     | This updates the PWM duty cycles, stepgen rates, and GPIO outputs on the FPGA. Any changes to configuration pins such as stepgen timing, GPIO inversions, etc, are also effected by this function. |
-
-Example:
-```
-loadrt threads name1=servo-thread period1=1000000
-addf test.0.read servo-thread
-# Add any function between the `read` and `write` routine of LitexCNC
-addf test.0.write servo-thread
-```
-
-### Pins and parameters
-
-#### GPIO
-
-> By default, the name of the pin is as defined in the JSON and uses the LiteX name of the pin (for example `j13:6`, meaning connector 13, pin 6). When in the in the josn-configutation the field `alias` is set, this name will be used instead.
-
-| Pin        | Type | Description |
-|------------|------|-------------|
-|litexcnc_<BoardName>.<BoardNum>.<PinName>.in | (bit out) | State of the hardware input pin.
-|litexcnc_<BoardName>.<BoardNum>.<PinName>.in_not | (bit out) | Inverted state of the hardware input pin.
-|litexcnc_<BoardName>.<BoardNum>.<PinName>.out | (bit in) | Value to be written (possibly inverted) to the hardware output pin.
-
-| Parameter  | Type | Description |
-|------------|------|-------------|
-|litexcnc_<BoardName>.<BoardNum>.<PinName>.invert_output | (bit in) | If this parameter is true, the output value of the GPIO will be the inverse of the value on the "out" HAL pin.
-
-## Supported boards
-All boards which support [LiteEth](https://github.com/enjoy-digital/liteeth) are supported, this includes the re-purposed Colorlight 5a-75a, 5a-75e, i5 and i9 boards. A full list of boards supported by LiteX and whether LiteEth is supported can be found [here](https://github.com/litex-hub/litex-boards).
-
-The structure of the driver allows to add more communication protocols in the future. I'm looking forward to add USB support as well. However, due to the nature of USB-communication this will most likely not result in real-time behaviour.
+For a full overview on how to use the commands, please refer to the `documentation <https://litex-cnc.readthedocs.io/en/stable/>`_.

docs/src/examples/index.rst

@@ -7,9 +7,6 @@ Examples
 For the supported cards ``5A-75B`` and ``5A-75E`` some examples can be downloaded using the 
 links below. 
 
-.. warning::
-    The examples section is work-in-progress. The links are not working at this moment.
-
 5A-75B
 ======
 
@@ -32,12 +29,12 @@ examples are:
    :header: "Board version", "IP-address", "GPIO (in/out)", "PWM", "Stepgen (type)", "Encoders (type)", "Change buffers", "Link"
    :widths: auto
 
-   "V6.1", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v6.1_i12o14p6s6e6.json>` / :download:`named <./named/5a-75b_v6.1_i12o14p6s6e6.json>`
-   "V6.1", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v6.1_i24o32.json>` / :download:`named <./named/5a-75b_v6.1_i24o32.json>`
-   "V7.0", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v7.0_i12o14p6s6e6.json>` / :download:`named <./named/5a-75b_v7.0_i12o14p6s6e6.json>`
-   "V7.0", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v7.0_i24o32.json>` / :download:`named <./named/5a-75b_v7.0_i24o32.json>`
-   "V8.0", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v8.0_i12o14p6s6e6.json>` / :download:`named <./named/5a-75b_v8.0_i12o14p6s6e6.json>`
-   "V8.0", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`indexed <./indexed/5a-75b_v8.0_i24o32.json>` / :download:`named <./named/5a-75b_v8.0_i24o32.json>`
+   "V6.1", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`JSON <./json/5a-75b_v6.1_i12o14p6s6e6.json>` :download:`pre-built <./json/zipped/5a-75b_v6.1_i12o14p6s6e6.zip>`
+   "V6.1", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`JSON <./json/5a-75b_v6.1_i24o32.json>` :download:`pre-built <./json/zipped/5a-75b_v6.1_i24o32.zip>`
+   "V7.0", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`JSON <./json/5a-75b_v7.0_i12o14p6s6e6.json>` :download:`pre-built <./json/zipped/5a-75b_v7.0_i12o14p6s6e6.zip>`
+   "V7.0", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`JSON <./json/5a-75b_v7.0_i24o32.json>` :download:`pre-built <./json/zipped/5a-75b_v7.0_i24o32.zip>` 
+   "V8.0", "192.168.2.50", "12 / 14", "6", "6 (step/dir)", "6 (A/B)", "U28, U24, U23", :download:`JSON <./json/5a-75b_v8.0_i12o14p6s6e6.json>` :download:`pre-built <./json/zipped/5a-75b_v8.0_i12o14p6s6e6.zip>` 
+   "V8.0", "192.168.2.50", "24 / 28", "6", "\-", "\-", "U28, U24, U23", :download:`JSON <./json/5a-75b_v8.0_i24o32.json>` :download:`pre-built <./json/zipped/5a-75b_v8.0_i24o32.zip>` 
 
 5A-75E
 ======
@@ -60,7 +57,7 @@ examples are:
    :header: "Board version", "IP-address", "GPIO (in/out)", "PWM", "Stepgen (type)", "Encoders (type)", "Change buffers", "Link"
    :widths: auto
 
-   "V6.0", "192.168.2.50", "30 / 29", "9", "9 (step/dir)", "9 (A/B)", "TBD", `index <test.html>`_
+   "V6.0", "192.168.2.50", "30 / 29", "9", "9 (step/dir)", "9 (A/B)", "TBD", :download:`JSON <./json/5a-75e_v6.0_i48o56.json>` :download:`pre-built <./json/zipped/5a-75e_v6.0_i48o56.zip>` 
    "V6.0", "192.168.2.50", "30 / 32", "6", "6 (step/dir diff.)", "6 (A/B/Z)", "TBD", `index <test.html>`_
-   "V7.1", "192.168.2.50", "30 / 29", "9", "9 (step/dir)", "9 (A/B)", "TBD", `index <test.html>`_
+   "V7.1", "192.168.2.50", "30 / 29", "9", "9 (step/dir)", "9 (A/B)", "TBD", :download:`JSON <./json/5a-75e_v6.0_i48o56.json>` :download:`pre-built <./json/zipped/5a-75e_v6.0_i48o56.zip>` 
    "V7.1", "192.168.2.50", "30 / 32", "6", "6 (step/dir diff.)", "6 (A/B/Z)", "TBD", `index <test.html>`_