Community

This documentation is open to be edited by all CODESYS Forge developers.
The documentation is intended to share global information, which is of interest for developers of different projects.

The contents of the documentation is not meant dogmatic and should provide the reader with enough tips & tricks to help write code which is clearly readable and quicker understood by the community.

The developer adhering to these tips & tricks, in return, will reap the benefits in an obvious manner. So, following tips & tricks is strongly encouraged!

• Software hints
• Workflows
• Tutorials
• Coding tips, - standards or - styles
• ...

Recommended Software

CODESYS programming

Use the CODESYS programming system in the latest version. It's use is completely free.

You can the program every CODESYS programmable PLC with it, or use the 2h Demo of one of the SL runtimes:

• CODESYS Control Win V3
• CODESYS Control for Raspberry Pi SL
• CODESYS Control for Linux SL

The demos are running 2h and can be restarted as often as you want.
These can also run demos of fieldbus stacks, which will run for 30m before a restart is needed.

Version Control System

You should use SVN when you want to have a good version control system with CODESYS projects, and if you want to publish them on CODESYS Forge.

CODESYS SVN can be freely used with CODESYS Forge. But we reconnend to use the tool cforge, as it improves the workflow with CODESYS Forge pretty much.

CODESYS Git is expected to be available in the next SP.

Versioning

Project versions

When it comes to library compatibility, the rule is really as easy as that:

"The CODESYS version of the user should be greater or equal to the format of the library."

Things like the compiler version, visu profile, etc. will usually be used from the final project, not from the library.

Of course there are some known exceptions;
;
;
* etc

Versioning of own items

The following version scheme suggestion is empirical in nature;

 v0.0.0.1    Initial version: Your first library / project in beta stage

whenever you code or bugfix just arbitrarily count up as you see fit, there is no right or wrong;

 v0.0.0.2    Bugfixes/coding version 2
 ..
 v0.0.0.49   Bugfixes/coding version 49
 etc, etc.

whenever you have tested a complete stable internal version;

 v0.0.1.0    your first stable version (tested)
 ..
 v0.0.1.3    your first stable version (tested) with some bugfixes
 ..
 v0.0.2.0    your second stable version (tested)
 ..
 v0.0.3.11   your third stable version (tested) with more bugfixes
 etc, etc.

whenever you have software which you have tested externally (public beta);

 v0.1.0.0    your first public beta version (tested/ publicly released)
 ..
 v0.1.0.2    your first public beta version (tested/ publicly released) with some bug fixes
 ..
 v0.2.0.0    your second public beta version (tested/ publicly released)
 etc, etc.

Whenever you have a stable public alpha release;

 v1.0.0.0    Your first alpha released version
 ..
 v1.0.0.6    Your first alpha released version with some bugfixes
 ..
 v1.1.0.9    An alpha released version with a beta tested/released component and some bugfixes
 ..
 v2.0.0.0    Your second alpha released version
 etc, etc.

As seen, this versioning scheme leaves "room" for (arbitrarily) smaller or larger code updates while also providing a clear overview of the development progress.

Of course, other versioning scheme's are possible (provide examples).

A versioning scheme I have used successfully for machines is this:

Vx.y.z
I will start in the middle as that is the most important, the state.
y = 0 = concept (just messing around with an idea)
y = 1 = development (goal in mind)
y = 2 = released for internal testing (devoloper thinks they are finished and are ready to run through internal testing)
y = 3 = released for stakeholder testing (testing complete, ready for testing with eg. Customer or product owner)
y = 4 = released for site (this version has all the testing and is ready for site)
y = 5 = installed on site (this version is installed on site, but is either not working or hasn't been tested)
y = 6 = commissioned (installed on site and somebody (customer?) is satisfied that it is working)

Now let's look to the least significant, version z. The first time you enter a new state you are on z=0. Any commits in that state, and z=z+1; Easy right?

Now the most significant, version x. The rule is "you cannot go backwards in y without incrementing x."

So that is the rules all covered. Now to some nuances or "what about when...".

Say you are in V0.3.0 (first stakeholder testing version) and the customer says "I want red to mean on". You do not need to go back to development stage or internal testing. You can simply make the change and commit as "V0.3.1 red now means on", then continue testing.
But what if next they said "you completely forgot the intake section of the machine specification!" Perhaps they threw the acceptance test sheets into the air and stormed out of the room. You can probably understand the state (y) may need to go back to development. So, your next commit is V1.1.0.

OK, so fast forward to commissioning. It is day 3 of commissioning and you are on V1.5.14. The customer is happy. You now make a commit (with no code changes from V1.5.14) to V1.6.0. The commit message might say something like "customer happy with site test" or even "developer happy the software is working" if that's how you run things.

A couple months later the customer asks "can you add an OFF delay to input 3?" You come round, do the change online, customer tests it and says it is fine. Just use V1.6.1 for your next commit.

A further 3 months and another small change is asked for. "We would like a trend of input 6." You go in on a down day, make the software change, but there's no product so you can't really test it. Commit the change as V2.5.0 (y=5, increase x by 1, reset z to zero). Two days later you check in with the customer. "All is good". Now you get a new commit, V2.6.0.

It is possible to skip steps as well. e.g. If it's decided a Factory Acceptance Test (y=3) isn't needed, go straight to 4.

Coding tips

• when using RTS_IEC_HANDLE and RTS_IEC_RESULT types, please add SysTypes2 Interfaces (3.5.4.0);
• if possible, use standard error codes (CmpErrors or CmpErrors2 Interfaces);
• if possible, avoid using dynamic memory (the usage of NEW operator);
• usage of Structured Text (IEC-ST) language is highly encouraged whenever possible. ST is by far the most versatile and universal language in which all operations manipulations and functions are possible;
• document the source code, add meaningful comments to it;
• for modern coding style advice: read the CODESYS v3 library development tips as provided in CODESYS help,
  The tips and practices laid out in the CODESYS help are pretty complete but not as thorough as Steve McConnell "Code Complete", though they provide a very good starting point.
  For further reading see e.g. Steve McConnell "Code Complete";

Forge Tips

• If you want to experiment with markdown syntax, create a project on your profile called "internaltest" and take away permissions of everyone but you.
• Use the "Create..." button in the top right menu bar for easy access of a wizard for creating and sharing community driven content.