v.2.0.2

[2.0.2] - 14.12.2024

IMPORTANT: This is a major version update. There are lots of breaking changes!

Updating v1 -> v2 requires manual changes to your codebase!

See MIGRATION.md for all breaking changes and follow the instructions.

Special thanks

• Special thanks to Christian Rishøj for valuable contribution!

Changes

• v.2.01 & v.2.02: Readme fixes - messed up with the links
• Everything rewritten in TypeScript
• Everything is tested before releasing
• Lots of optimizations
• Lots of name changes
• New methods: resetPlc(), readWriteRawMulti(), writeRawByPath(), readValueBySymbol(), writeValueBySymbol()
• New setting disableCaching: disables all symbol and data type caching
• Added optional targetOpts argument in all methods
  • Possible to provide different target address (AmsNetId and/or AdsPort) than specified in the settings
  • Caching is only available for the original target provided in settings
  • The same client can be used for many different targets at the same time
• Added support for reading/writing INTERFACE data types
• Added support for reading/writing empty FUNCTION_BLOCKs
• Added support for reading/writing BIT data type
• Writing a STRING or WSTRING value that is longer than the target data type causes the string to be truncated.
  • Previously the string end character was lost, which caused "never ending string" and <Value of the expression cannot be retrieved in PLC online view.
  • E.g. writing 85 bytes of string to STRING(80) variable
• BOOL and BIT data values are now true if the value is anything else than 0
  • In TwinCAT, BOOL is true if the value is anything else than zero (see x_TO_BOOL)
  • Before, ads-client set the value to true only if value was true or 1, otherwise it was 0
• writeControl() accepts also string values for adsState
• Added support for UTF-8 encoded ADS symols
  • Required for TwinCAT 3.1.4026 support
  • Required for TwinCAT 3.1.4022/3.1.4024 with UTF-8 Encoding checked under TwinCAT XAE -> SYSTEM -> Settings -> ADS Symbolic.
• Added new metaData.adsSymbolsUseUtf8
  • Set true if target system is using UTF-8 for ADS symbol encoding
• Added new setting forceUtf8ForAdsSymbols (default: false)
  • If set, client always handles ADS symbols as UTF-8 encoded
  • Otherwise tries to detect the encoding or fallbacks to cp1252
• readPlcUploadInfo() updated to support new version 3 upload info (inc. ADS symbol encoding info)
  • Also added support for old version 1 upload info (perhaps old TC2 devices..?)
• New method sendAdsCommandWithFallback()
  • Calls sendAdsCommand() with a specific command. If it fails to certain ADS errors, tries the fallback command.
• Added test suites for TwinCAT 2
  • Separate TwinCAT 2 test PLC project created (See https://github.com/jisotalo/ads-client-test-plc-project/tree/v2-dev)
  • Updated tests to work with TC2 (and removed tests for TC2 unsupported features)
• Added warning event to listen for console warnings