diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000..382ef33f --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,18 @@ +on: push + +jobs: + contrib-readme-job: + runs-on: ubuntu-latest + name: A job to automate contrib in readme + permissions: + contents: write + pull-requests: write + steps: + - name: Contribute List + uses: akhilmhdh/contributors-readme-action@v2.3.11 + with: + use_username: true + commit_message: "[ROOT][DOCS] contrib-readme-action has updated readme" + pr_title_on_protected: "[ROOT][DOCS] contributors readme action update" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..2e470d1d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# CANopenEditor Contributing Guidelines + +Thank you for your interest in contributing to this project!
+Being a well referenced EDS/DCF editor and the only one supporting CANopenNode, CANopenEditor let everyone manage CANopen files, completely free of charge!
+CANopenEditor is maintained by a small team of volunteers from around the world. As such, those rules are meant for a better communication between everyone but, any help being very welcome, reviewers might approve PRs not respecting all of these rules as long as you tried. Project owners are above those rules as they might have specific needs.
+Please note that by contributing to this project, you agree to have read this file and to the [Developer's Certificate of Origin 1.1](https://developercertificate.org/). + +## Discussions +Discussions shall be done in respect to everyone and everyone's work. +Any major change shall be first discussed in an issue. Do not worry: maintainers are quite active and will answer. + +## Code convention +This project doesn't really follow any real code convention and doesn't have any linter for now BUT following [common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) is very welcome and might be asked of you if some parts of your code are too hard to read. +If linting is ever needed, `dotnet format` will be our solution of choice. +Even tho there is no hard-defined conventions, non-explicit names or lack of spacing might result in non-approval of a PR. + +## What might or might not be a PR +A simple refactor of code without any real change won't ever be approved. This project relies quite a bit on git blame and as such you are only allowed to refactor code you change. Moreover, trying to enforce a code convention without approval of the main maintainers first might be seen as disrespectful. + +## Testing +Any code change shall be tested. You can: +- Add unit tests in the right directories +- Describe any tests you did with the files you might have used + +Code that you didn't even try to compile won't be accepted. + +## Code comments +- Complex algorithms MUST be explained with code comments. +- Hardcoded values (e.g. specific numbers in the middle of nowhere) MUST be justified with code comments. +- Non explicit data structures (e.g. an array of set size with every index having a meaning) MUST be explained with code comments. +- Commented lines of code MUST be preceded by a comment line starting with either `//// DEBUG code:` or `//// TODO:`. +- Comments SHALL have a space between the comment string (e.g. `//`) and the text content. +- Functions and methods MIGHT have comments describing what they are doing, what are their inputs and/or outputs (if it's not explicit enough). +- Loops and switches MIGHT have comments justifying why every case is taken into account (if it's not explicit enough). +- Any more useful comment is welcome. + +## Names and descriptions +### PR names +They shall be composed of three sections: +1) Which project is affected (MIX if multiple) +2) What types of changes are made (e.g. FEAT, FIX, DOCUMENTATION/DOC, CORRECTION/CORR, SUGGESTION/SUGG, BUILD, ...) +3) An explicit but less than 100 chars long summary of the changes + +Sections shall be clearly separated (e.g. with colons, parenthesis, ...).
+Examples of valid and explicit PR names: `[MIX][DOC] Explaining explicit PR title rules`, `gui2: fix: Fixed bug where 1 = 2`.
+If you have multiple unrelated changes (e.g. adding a feature and fixing another) to do, please do multiple PRs. + +### PR descriptions +They shall: +- Describe any change made +- Explain why such changes are made +- Explain any decision taken +- Link any related issue / any related other PR +- Describe any test made +- The sentence "I have read the contributing guidelines, I agree to following them and I agree to the Developer's Certificate of Origin 1.1" + +### Commits +Names shall be composed of: +1) What types of changes are made (e.g. PR names sections 2) +2) An explicit but less than 100 chars long summary of the changes + +Descriptions are entirely up to you. diff --git a/EDSEditorGUI/README.md b/EDSEditorGUI/README.md new file mode 100644 index 00000000..c7acfff4 --- /dev/null +++ b/EDSEditorGUI/README.md @@ -0,0 +1,52 @@ +GUI +============= +* Open multiple devices +* Open EDS/DCF/XDC files +* Save EDS/DCF/XDC files +* View OD Entries and explore the Object Dictionary +* Add new OD entries +* Delete exisiting OD entries +* Create new Devices +* Add default profiles +* Create profiles that can be added to any project (just save the device xml file to the profiles/ directory, only include the minimum number of objects that you want to auto insert); This will auto add to insert menu +* Edit Device and File Info sections +* Set RX/TX PDO mappings easily from dropdown lists of available objects +* Add and remove new PDO entries (communication paramaters and mapping) with a single button's push +* Save groups of EDS/XML files as a network object with ability to set concrete node IDs +* View report of all configured PDOs across the network +* View modules and module details present within EDS files +* View/edit actual object values for device configuring/DCF files +* Support for loading XDD files (CanOpen offical XML) +* Support for saving XDD files (CanOpen offical XML) +* Some module info is displayed in GUI showing available modules (eds) and configured modules (dcf) and what OD entries they reference. + Full details such as subobj extension and fixed subobj are not currently displayed and unless there is demand probably will not ever be. + +[Available formats' list can be found here](https://github.com/CANopenNode/CANopenEditor?tab=readme-ov-file#available-formats). + +Pictures +------------- +For those pictures, the file shown is: https://www.hbm.com/fileadmin/mediapool/support/download/weighing/pad/PAD4000_P80_113_01_COS.EDS + +### General informations +![General informations tab](../Images/General%20infos.png) + +### OD manipulation +![OD when you select an object](../Images/OD%20selected%20object.png) +![OD's communication specific parameters](../Images/OD%20comm%20specific%20param.png) + +### PDO manipulation +TPDO:
+![TPDO tab](../Images/TPDO.png) +RPDO:
+![RPDO tab](../Images/RPDO.png) +PDO editing:
+![PDO edition](../Images/Edit%20PDO.png) + +### Modules +![Modules tab](../Images/Modules.png) + +### Profiles +Available profiles:
+![Profiles option](../Images/Profiles.png) +Applying a profile:
+![Profiles application](../Images/Applying%20profile.png) diff --git a/EDSEditorGUI2/README.md b/EDSEditorGUI2/README.md new file mode 100644 index 00000000..edb55896 --- /dev/null +++ b/EDSEditorGUI2/README.md @@ -0,0 +1,5 @@ +GUI2 +============= +This GUI is meant to be cross-platform, meant to replace the old GUI and is made using Avalonia. It is not yet ready. +
+[Available formats' list can be found here](https://github.com/CANopenNode/CANopenEditor?tab=readme-ov-file#available-formats). diff --git a/EDSSharp/README.md b/EDSSharp/README.md new file mode 100644 index 00000000..66e6dbfc --- /dev/null +++ b/EDSSharp/README.md @@ -0,0 +1,24 @@ +EDSSharp +============= + +A C# CanOpen EDS (Electronic Data Sheet) library, CLI convertor and GUI editor. + +This application is designed to load/save/edit and create EDS/DCF/XDC file for CANopen and also to generate the object dictionary for CANopenNode (V1.3 and newer) to aid development of CANopenNode devices. + +EDS (Electronic Data Sheet) files are text files that define CANopen devices. +DCF (Device Configuration File) files are text files that define configured CANopen devices. +XDD files are an XML version of EDS files. + +EDS/DCF are fully defined in the DSP306 standard by the CANopen standards body: CiA. + +The EDS editor on its own is useful without the CANopenNode specific export and, as of the 0.6-XDD-alpha version, the editor can also load/save XDD files. +The GUI also shows PDO mappings and can generate reports of multiple devices that are loaded into the software. + +The core library can be used without the GUI to implement eds/xdd loading/saving and parsing etc in other projects. + +Please consider this code experimental and beta quality. +It is a work in progress and is rapidly changing. + +Every attempt has been made to comply with the relevant DSP306 and other standards and EDS files from multiple sources have been tested for loading/saving and as been (at times) validated for errors using EDS conformance tools. + +[Available exporters' list can be found here](https://github.com/CANopenNode/CANopenEditor?tab=readme-ov-file#available-formats). diff --git a/GUITests/README.md b/GUITests/README.md new file mode 100644 index 00000000..0c72b618 --- /dev/null +++ b/GUITests/README.md @@ -0,0 +1,3 @@ +GUITests +============= +This directory contains unit tests for the avalonia (new) GUI. All tests shall be written in C# and run on all supported OS. diff --git a/Images/Applying profile.png b/Images/Applying profile.png new file mode 100644 index 00000000..d8d7d6b2 Binary files /dev/null and b/Images/Applying profile.png differ diff --git a/Images/Edit PDO.png b/Images/Edit PDO.png new file mode 100644 index 00000000..4fa23465 Binary files /dev/null and b/Images/Edit PDO.png differ diff --git a/Images/General infos.png b/Images/General infos.png new file mode 100644 index 00000000..f1dc3422 Binary files /dev/null and b/Images/General infos.png differ diff --git a/Images/Modules.png b/Images/Modules.png new file mode 100644 index 00000000..8eb65be8 Binary files /dev/null and b/Images/Modules.png differ diff --git a/Images/OD comm specific param.png b/Images/OD comm specific param.png new file mode 100644 index 00000000..ec5b6044 Binary files /dev/null and b/Images/OD comm specific param.png differ diff --git a/Images/OD selected object.png b/Images/OD selected object.png new file mode 100644 index 00000000..1ac405b3 Binary files /dev/null and b/Images/OD selected object.png differ diff --git a/Images/Profiles.png b/Images/Profiles.png new file mode 100644 index 00000000..281e7de3 Binary files /dev/null and b/Images/Profiles.png differ diff --git a/Images/README.md b/Images/README.md new file mode 100644 index 00000000..94e8d960 --- /dev/null +++ b/Images/README.md @@ -0,0 +1,13 @@ +Images +============= +Contains any and all images used in the documentation. Not all images in here are used but no image used in the documentation shall be anywhere but here. + +Here are some old pictures: +![Device info section of the GUI](pic2.jpg) +![OD section of the GUI](pic1.jpg) +![TX PDO Mapping section of the GUI](pic3.jpg) +![A specific PDO view in the GUI](pic4.jpg) +![New object dictionnary index](newod.png) +![Object dictionnary details](ODDetails.png) +![Object dictionnary details edition](ODDetailsEdit.png) +![Object dictionnary entries list](ODList.png) diff --git a/Images/RPDO.png b/Images/RPDO.png new file mode 100644 index 00000000..0ee1b458 Binary files /dev/null and b/Images/RPDO.png differ diff --git a/Images/TPDO.png b/Images/TPDO.png new file mode 100644 index 00000000..95a6da81 Binary files /dev/null and b/Images/TPDO.png differ diff --git a/pic1.jpg b/Images/pic1.jpg similarity index 100% rename from pic1.jpg rename to Images/pic1.jpg diff --git a/pic2.jpg b/Images/pic2.jpg similarity index 100% rename from pic2.jpg rename to Images/pic2.jpg diff --git a/pic3.jpg b/Images/pic3.jpg similarity index 100% rename from pic3.jpg rename to Images/pic3.jpg diff --git a/pic4.jpg b/Images/pic4.jpg similarity index 100% rename from pic4.jpg rename to Images/pic4.jpg diff --git a/README.md b/README.md index bf2fce65..e4209fa8 100644 --- a/README.md +++ b/README.md @@ -1,121 +1,308 @@ CANopenEditor ============= -CANopenEditor is a fork from https://github.com/robincornelius/libedssharp, author Robin Cornelius. -Its homepage is https://github.com/CANopenNode/CANopenEditor +CANopenEditor is a fork from [libedssharp, authored by Robin Cornelius](https://github.com/robincornelius/libedssharp). +CANopenEditor's homepage is https://github.com/CANopenNode/CANopenEditor. CANopen Object Dictionary Editor: - Imports: CANopen electronic data sheets in EDS or XDD format. - - Exports: CANopen electronic data sheets in EDS or XDD format, documentation, CANopenNode C source files. - - GUI editor for CANopen Object Dictionary, Device information, etc. + - Exports: CANopen electronic data sheets in EDS or XDD format, documentation, CANopenNode C source files and more. + - Interfaces: GUI editor for CANopen Object Dictionary, Device information, etc. CLI client for simple conversions. -CANopen is the internationally standardized (EN 50325-4) ([CiA301](http://can-cia.org/standardization/technical-documents)) higher-layer protocol for embedded control system built on top of CAN. For more information on CANopen see http://www.can-cia.org/ +CANopen is the internationally standardized (EN 50325-4) ([CiA301](http://can-cia.org/standardization/technical-documents)) higher-layer protocol for embedded control system built on top of CAN. For more information on CANopen see http://www.can-cia.org/ . -[CANopenNode](https://github.com/CANopenNode/CANopenNode) is free and open source CANopen Stack +[CANopenNode](https://github.com/CANopenNode/CANopenNode) is a free and open source CANopen Stack. +Repository structure +-------- +This repository is home to three projects: +- [LibEDSsharp](https://github.com/CANopenNode/CANopenEditor/blob/docs/libEDSsharp/README.md), a C# library for EDS files manipulation which went upstream and is now maintained in this repository. +- [A CLI](https://github.com/CANopenNode/CANopenEditor/blob/docs/EDSSharp/README.md), used for simple conversions across all supported formats. +- [A GUI](https://github.com/CANopenNode/CANopenEditor/blob/docs/EDSEditorGUI/README.md) for full manipulation of your CANopen files [which is being rewritten to be more multi platform](https://github.com/CANopenNode/CANopenEditor/blob/docs/EDSEditorGUI2/README.md). -EDSSharp +How to use -------- +1. [Download the latest release's binary zip file](https://github.com/CANopenNode/CANopenEditor/releases). DO NOT DOWNLOAD SOURCE CODE. +2. Unzip it. +3. Go to net8.0-windows directory. +4. Execute the .exe . -A C# CanOpen EDS (Electronic Data Sheet) library and GUI editor - -This application is designed to load/save/edit and create EDS/DCF/XDC file for -CanOpen and also to generate the object dictionary for CanOpenNode -CO_OD.c and CO_OD.h) to aid development of CanOpenNode devices. - -EDS (Electronic Data Sheet) files are text files that define CanOpen Devices. -DCF (Device Configuration File) files are text files that define configured -CanOpenDevices XDD files are an XML version of EDS files - -EDS/DCF are fully defined in the DSP306 standard by the can open standards -body CiA. - -The EDS editor on its own is useful without the CanOpenNode specific export and -as of the 0.6-XDD-alpha version the editor can also load/save XDD files. -The GUI also shows PDO mappings and can generate reports -of multiple devices that are loaded into the software. - -The core library can be used without the GUI to implement eds/xdd loading/saving -and parsing etc in other projects. - -Please consider this code experimental and beta quality. -It is a work in progress and is rapidly changing. - -Every attempt has been made to comply with the revelant DSP306 and other -standards and EDS files from multiple sources have been tested for loading and -saving as been (at times) validated for errors using EDS conformance tools. - -With many thanks to the following contributors for spotting my mistakes and -improving the code - * s-fuchs - * martinwag - * trojanobelix - * many others... - -Library -------- - -* Read EDS/DCF/XDC file and parse contents to approprate classes -* Dump EDS/DCF classes via ToString() -* Save EDS/DCF classes back to EDS file -* Export C and H files in CanOpenNode format CO_OD.c and CO_OD.h -* EDS/DCF supports modules -* EDS/DCF supports compactPDO (read only) *¹ -* EDS/DCF supports implict PDO (read only) *¹ -* EDS/DCF supports CompactSubOb (read only) *¹ -* Supports loading/saving of all EDS/DCF module information - -*¹ Read only, in this context, means the EDS/DCF is fully expanded but the compact - forms is not written back, only the expanded form will be saved. - -GUI ---- -* Open multiple devices -* Open EDS/DCF/XDC files -* Save EDS/DCF/XDC files -* View OD Entries and explore the Object Dictionary -* Add new OD entries -* Delete exisiting OD entries -* Create new Devices -* Add default profiles -* Create profiles that can be added to any project (just save the device xml file to the profiles/ - directory, only include the minimum number of objects that you want to auto insert) This will auto add to insert menu -* Edit Device and File Info sections -* Set RX/TX PDO mappings easily from dropdown lists of available objects -* Add and remove new PDO entries (communication paramaters and mapping) in a single button push -* Save groups of EDS/XML files as a network object with ability to set concrete node IDs -* View report of all configured PDOs across the network -* View modules and module details present within EDS files -* View/edit actual object values for device configuring/DCF files -* Support for loading XDD files (CanOpen offical XML) -* Support for saving XDD files (CanOpen offical XML) -* Some module info is displayed in GUI showing available modules (eds) and - configured modules (dcf) and what OD entries they reference. Full details such - as subobj extension and fixed subobj are not currently displayed and unless - there is demand probably will not ever be. - -TODO ----- - -* Ensure and validate all XDD is loading/save correctly (Looking good so far) -* Add extra Gui fields for accessing extra XDD paramaters not in EDS - (all common ones are done, a few special/edge cases remain) -* Look at XDC files and see if we can save config changes and allow editing and - network setup here in the app, partial support is implemented by supporting - DCF files +Available formats +-------- +Exhaustive list of the library's supported formats to date, sorted by category:
+### CAN in Automation official formats: +| Description | Exporter | Format | +|---------------------------------------|------------------------------------------------------------|--------| +| Electronic Data Sheet (CiA 306-1) | ElectronicDataSheet | .eds | +| Device Configuration File (CiA 306-1) | DeviceConfigurationFile | .dcf | +| XML Device Description (CiA 311) | CanOpenXDDv1.0
CanOpenXDDv1.1
CanOpenXDDv1.1stripped | .xdd | +| XML Device Configuration (CiA 311) | CanOpenXDCv1.1 | .xdc | -BUGS ----- +### Extended formats: +| Description | Exporter | Format | +|----------------------------------|---------------------------------------------|--------| +| Network XML Device Description | CanOpenNetworkv1.0
CanOpenNetworkXDDv1.1 | .nxdd | +| Network XML Device Configuration | CanOpenNetworkXDCv1.1 | .nxdc | +| XML Profile Description | None | .xpd | + +### CANopenNode specific formats: +| Description | Exporter | Format | +|------------------------------------------|----------------------------------------------------------|-----------------| +| CanOpenNode Object Dictionary file pairs | CanOpenNode
CanOpenNodeV4 | .h,.c | +| PCanOpenNode Project file | CanOpenNodeProtobuf(json)
CanOpenNodeProtobuf(binary) | .json
.binpb | + +### Documentation formats: +| Exporter | Format | +|---------------------|--------| +| DocumentationHTML | .html | +| DocumentationMarkup | .md | +| NetworkPDOReport | .md | + +File structure +-------- +The main files and directories you'll need to understand are: +- [setup.nsi](https://github.com/CANopenNode/CANopenEditor/blob/main/setup.nsi) is the Windows installer. +- [Makefile](https://github.com/CANopenNode/CANopenEditor/blob/main/Makefile) is the Linux installation and manipulation script. +- [EDSEditorGUI](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSEditorGUI) directory is the old GUI. Fully functional but only works on Windows. +- [EDSEditorGUI2](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSEditorGUI2) directory is the new GUI. It is not fully finished yet but is meant to work on any Windows, Mac or Linux OS. +- [EDSSharp](https://github.com/CANopenNode/CANopenEditor/tree/main/EDSSharp) directory is the CLI. It is only meant for simple conversions for now. +- [GUITests](https://github.com/CANopenNode/CANopenEditor/tree/main/GUITests) directory is the directory for all GUI unit tests. More tests, functional tests and tests for GUI2 may come here. +- [Images](https://github.com/CANopenNode/CANopenEditor/tree/main/Images) directory is the directory containing any and all of the documentation's images. +- [Tests](https://github.com/CANopenNode/CANopenEditor/tree/main/Tests) directory is the directory for all Lib unit tests. More tests, functional tests and tests for CLI may come here. +- [libEDSsharp](https://github.com/CANopenNode/CANopenEditor/tree/main/libEDSsharp) directory contains the library from Robin Cornelius making all of this work. -If you find any, please open a bug report on github and attach any files you -have created/opened etc. +BUGS +-------- +If you find any, please open a bug report on github and attach any files you have created/opened etc... We need any help we can have and the main maintainers are quite active and will answer you fast. You might want to check your EDS/XDD file with this free [EDSchecker](https://www.vector.com/de/de/support-downloads/download-center/#product=%5B%2274771%22%5D&tab=1&pageSize=15&sort=date&order=desc) -Pictures +Contributing -------- +If you want to help us out by contributing to this project, first of all thank you ! And please read our [Contributing Guidelines](https://github.com/CANopenNode/CANopenEditor/blob/docs/CONTRIBUTING.md). We are very beginner friendly so, even if you are not extremely experienced with contributing to open source projects, fear not and try ! -![alt tag](pic1.jpg) -![alt tag](pic2.jpg) -![alt tag](pic3.jpg) -![alt tag](pic4.jpg) +Collaborators +-------- + + + + + + + +
+ + reza0310 +
+ reza0310 + +
+ + +Contributors +-------- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + robincornelius +
+ robincornelius + + 		+ + trojanobelix +
+ trojanobelix + + 		+ + nimrof +
+ nimrof + + 		+ + CANopenNode +
+ CANopenNode + + 		+ + martinwag +
+ martinwag + + 		+ + simon-fuchs-inmach +
+ simon-fuchs-inmach + +
+ + heliochronix +
+ heliochronix + + 		+ + Bartimaeus- +
+ Bartimaeus- + + 		+ + cfr-mir +
+ cfr-mir + + 		+ + JuPrgn +
+ JuPrgn + + 		+ + gotocoffee1 +
+ gotocoffee1 + + 		+ + wilkinsw +
+ wilkinsw + +
+ + pettaa123 +
+ pettaa123 + + 		+ + henrikbrixandersen +
+ henrikbrixandersen + + 		+ + ckhardin +
+ ckhardin + + 		+ + Regelink +
+ Regelink + + 		+ + DylanRobertBennett +
+ DylanRobertBennett + + 		+ + rgruening +
+ rgruening + +
+ + Barzello +
+ Barzello + + 		+ + rcolatobe +
+ rcolatobe + + 		+ + kekiefer +
+ kekiefer + + 		+ + zhanglongqi +
+ zhanglongqi + + 		+ + DaMutz +
+ DaMutz + + 		+ + StormOli +
+ StormOli + +
+ + possibly-not +
+ possibly-not + + 		+ + reza0310 +
+ reza0310 + + 		+ + KwonTae-young +
+ KwonTae-young + +
+ diff --git a/Tests/README.md b/Tests/README.md new file mode 100644 index 00000000..62ba29c0 --- /dev/null +++ b/Tests/README.md @@ -0,0 +1,3 @@ +Tests +============= +This directory contains unit tests for the library and CLI. All tests shall be written in C# and run on all supported OS. diff --git a/libEDSsharp/README.md b/libEDSsharp/README.md new file mode 100644 index 00000000..e8057e25 --- /dev/null +++ b/libEDSsharp/README.md @@ -0,0 +1,17 @@ +libEDSsharp +============= +The library making it all work. + +* Read EDS/DCF/XDC file and parse contents to appropriate classes +* Dump EDS/DCF classes via ToString() +* Save EDS/DCF classes back to EDS file +* Export C and H files in CANopenNode format (V1.3 and newer) +* EDS/DCF supports modules +* EDS/DCF supports compactPDO (read only) \*¹ +* EDS/DCF supports implict PDO (read only) \*¹ +* EDS/DCF supports CompactSubOb (read only) \*¹ +* Supports loading/saving of all EDS/DCF module information + +\*¹ Read only, in this context, means the EDS/DCF is fully expanded but the compact forms is not written back, only the expanded form will be saved. +
+[Available exporters' list can be found here](https://github.com/CANopenNode/CANopenEditor?tab=readme-ov-file#available-formats).