AXIOMATIC AX140910 CAN-ENET Software Support Package User Manual

AXIOMATIC AX140910 CAN-ENET Software Support Package

Product Information

The CAN-ENET Software Support Package (SSP) is a set of software modules, documentation, and examples for developing application software that works with various Axiomatic Ethernet to CAN and Wi-Fi to CAN converters. The software package provides a user manual, source files, and examples. The user manual is valid for any SSP version 3.0.xx, and updates specific to the user manual are done by adding letters A, B, …, Z to the user manual version number. The SSP can be used for programming embedded systems with limited resources as well as for application programming in Windows or Linux.

Product Usage

1. Download the distribution zip file from the Axiomatic website or receive it as an attachment via email.
2. Unblock the zip file in Windows by right-clicking the file and pressing the Unblock button in Properties->General->Unblock.
3. Extract the zip archive to create the following folder structure:
   • The root directory contains the SSP help file CANEnetSSP.chm in the Microsoft HTML help format and the user manual UMAX140910v3.0.pdf in the Adobe Reader format.
   • The Source Files folder contains the converter health status information described in the Ethernet to CAN Converter Communication Protocol.
   • The Examples folder contains examples that can be built on Microsoft Windows or Linux using Windows.mk or Linux.mk make files.
4. Build executable files for the examples using the make files located in the .Examples directory.
5. If necessary, create a .Bin subdirectory in the .Examples directory where all executable and object files will be placed.
6. The SSP zip file contains compiled examples for Windows in the .Bin subdirectory.
7. All SSP examples were tested on Windows 10 and Linux Ubuntu 16.04.

The SSP uses only int and char standard data types. The int type is used when the exact or maximum data size for the integer parameter is not critical. The char type is used to point to an ASCII string or reference a single ASCII character. Other basic types are derived from the header and have the exact data size, except the Boolean type BOOL_t, which is derived from int, see: CommonTypes.h file.

ACRONYMS

• API Application Programming Interface
• ASCII American Standard Code for Information Interchange
• BSD Berkeley Software Distribution
• CAN Controller Area Network
• HTML HyperText Markup Language
• IP Internet Protocol
• LAN Local Area Network
• SSP Software Support Package

GENERAL INFORMATION

The CAN-ENET Software Support Package (SSP) provides a set of software modules, documentation, and examples for developing application software working with various Axiomatic Ethernet to CAN and Wi-Fi to CAN converters.
The user manual is valid for the SSP with the same two major version numbers as the user manual. For example, this user manual is valid for any SSP version 3.0.xx. Updates specific to the user manual are done by adding letters: A, B, …, Z to the user manual version number. All SSP software modules are written in a standard C programming language for portability and fully documented. They provide support for Axiomatic proprietary Communication and Discovery protocols. The Communication protocol is mainly used for transmitting CAN messages over Ethernet or any other IP network, and the Discovery protocol – for locating the converter on the LAN. The SSP can be equally used for programming embedded systems with limited resources and for application programming in Windows or Linux.

SSP CONTENTS

The SSP is distributed as a zip file with the name: CANEnetSSPv<X.X.XY>.zip, where <X.X.X> numbers refer to the SSP main version number and – to the optional documentation change letter. To avoid potential issues with displaying the SSP help file, the distribution zip file should be unblocked in Windows if acquired over the internet (after downloading from the Axiomatic website, receiving in e-mail as an attachment, etc.) This can be done by right-clicking the file and pressing the Unblock button in Properties->General->Unblock. After extracting the zip archive, the following folder structure will be created:

The root directory contains the SSP help file CANEnetSSP.chm in the Microsoft HTML help format and this user manual UMAX140910v3.0.pdf in the Adobe Reader format. The most significant SSP version number reflects incompatible changes, next – compatible changes, the last one – minor changes not affecting the SSP functionality. The optional letter is added for changes in the user manual and/or help file

Source Files
The SSP source files are grouped in .\Source and .\Inc directories according to their type. They are written in standard C and present the following software modules:

• PMessage. Provides support for the protocol independent message structure described in the Ethernet to CAN Converter Communication Protocol.
• CommProtocol. Supports messages from the Ethernet to CAN Converter Communication Protocol.
• DiscProtocol. Supports messages from the Ethernet to CAN Converter Discovery Protocol.
• HealthData. Provides data structures and functions for processing the Ethernet to CAN converter health status information described in the Ethernet to CAN Converter Communication Protocol.

All basic data types and common macros are defined in the CommonTypes.h file.

Examples
The SSP also contains the following example programs in the .\Examples directory demonstrating different scenarios of communication with the Axiomatic Ethernet to CAN converter:

• CANReceive.c. This console application shows how CAN frames can be received from the Axiomatic Ethernet to CAN converter.
• CANSend.c. This example demonstrates how CAN frames can be sent to the Axiomatic Ethernet to CAN converter.
• Discovery.c. This example application shows how the user can discover an Axiomatic Ethernet to CAN converter on the local area network (LAN).
• Heartbeat.c. This application demonstrates how Heartbeat messages can be received from the Axiomatic Ethernet to CAN converter. It also shows unpacking of the Health Data from Heartbeat messages.
• StatusRequest.c. This example application shows how the user can request the Axiomatic Ethernet to CAN converter status

All examples can be built on Microsoft Windows or Linux using Windows.mk or Linux.mk make files. The make files are also located in the .\Examples directory. Upon building executable files, the make script, if necessary, creates .\Bin subdirectory in the .\Examples directory where it places all executable and object files. The SSP zip file contains compiled examples for Windows in the .\Bin subdirectory. All SSP examples were tested on Windows 10 and Linux Ubuntu 16.04

DATA TYPES AND CODING STYLE

The SSP uses only int and char standard data types. The int type is used when the exact or maximum data size for the integer parameter is not critical. The char type is used to point to an ASCII string or reference a single ASCII character. Other basic types are derived from <stdint.h> header and have the exact data size, except the Boolean type BOOL_t, which is derived from int, see: CommonTypes.h file. All SSP exported basic types are named with capital letters and have the ‘_t’ ending. For example: BOOL_t, WORD_t, etc. All other exported types are named with capital letters, have the ‘_t’ ending and are prefixed with the file abbreviation for the file they are defined in. The ‘CP’ is used for the CommProtocol.h, ‘DP’ – for the DiscProtocol.h, ‘HD’ – for the HealthData.h and ‘PM’ – for the PMessage.h file. All macros names use capital letters and are prefixed with the file abbreviation for the file they are defined in, the same way as data types. The ‘CT’ abbreviation is used for the CommonTypes.h file.
The variable names are prefixed with their type for basic types and pointers. For example: int type is prefixed with ‘i’, pointer type – with ‘p’, pointer to integer – with ‘pi’, etc. Structures, unions, enumerators are not prefixed. For zero terminated strings, the ‘sz’ prefix is used. The function names are prefixed with the file abbreviation the same way as data types and macros. One tab is equal to four spaces

USING SSP

The user should add the SSP files to the application project. The CommProtocol.c or DiscProtocol.c can be excluded if the appropriate protocol is not used. The HealthData.c can also be excluded if there is no need to process the converter health data.
The SSP does not require initialization prior to use. It does not have any global variables. All SSP functions are thread-safe and reentrant. For sending and receiving the converter messages, a support of the Internet protocol (IP) is required. A standard way to provide this support is to use Internet sockets. The socket API is well standardized and is used in all SSP examples and for description of the converter operations.

Receiving Messages from the Converter
The user should first prepare a socket for receiving the converter data.
When the data is received, it should be passed to the PMParseFromBuffer() function. The user provides two callback functions: OnDataParsed() and OnDataParsedError(). The first function is invoked after the protocol message has been successfully parsed and the second one – on the parsing error. Then, the user should call parsers for individual protocol-specific messages inside the OnDataParsed() function, see below:

UMAX140910. CAN-ENET Software Support Package. Version 3.0

UMAX140910. CAN-ENET Software Support Package. Version 3.0

If the user wants to parse the dwHealthData value into individual operational statuses of the converter major hardware and software components, the HDUnpackHealthData() function should be called:

UMAX140910. CAN-ENET Software Support Package. Version 3.0 This function also returns the converter aggregated Health Status.

Sending Messages to the Converter
User messages can be sent to the converter by first generating the required protocol message and then copying the message to the transmitting buffer. For example, sending a status request will require the following commands

Sending CAN FD frames is more elaborated. The CAN FD Stream message can contain more than one CAN FD or Classical CAN frame, unless CP_SUPPORTED_FEATURE_FLAG_CAN_FD_STREAM_ONE_FRAME_PER_MESSAGE flag is set by the node in the Status Response or Heartbeat message. The user should first prepare an empty CAN FD Stream message and then add CAN frames to it.

UMAX140910. CAN-ENET Software Support Package. Version 3.0

If the TCP protocol is used, the TCP_NODELAY option should be set to the socket to avoid delays in sending protocol messages

Discovering the Converter
The converter can be discovered using the Ethernet to CAN Converter Discovery Protocol. The user should do the following:

• Open a datagram socket with the SO_BROADCAST option.
• Prepare a discovery request and copy it to the transmitting buffer.
• Send the discovery request to the global IP address.
• Wait for the incoming discovery responses from converters located on the same LAN.
• Parse the responses first by PMParseFromBuffer() and then by DPParseResponse() called from OnDataParsed() .

A simplified example code illustrating the concept is presented below

UMAX140910. CAN-ENET Software Support Package. Version 3.0

DOCUMENTATION

The following documents describing the Axiomatic proprietary protocols used in the SSP are available upon request:

• O. Bogush, “Ethernet to CAN Converter Communication Protocol. Document version: 5,” Axiomatic Technologies Corporation, December 14, 2022.
• O. Bogush, “Ethernet to CAN Converter Discovery Protocol. Document version: 1A,” Axiomatic Technologies Corporation, April 5, 2021.
• O. Bogush, ” Ethernet to CAN Converter Health Status. Document version: 3,” Axiomatic Technologies Corporation, April 5, 2021.

For requesting the documents, please contact Axiomatic Technologies at: sales@axiomatic.com

LICENSE

The SSP software is distributed with a permissive 3-clause BSD License. The text of the license is included in the software files

VERSION HISTORY

User Manual Version| SSP

version

| ****

Date

| ****

Author

| ****

Modifications

---|---|---|---|---
3.0| 3.0.0| December 14, 2022| Olek Bogush| ·         Added support for CAN FD Stream.

·         Deprecated support for CAN and Notification Stream.

·         Added Communication Node Settings to Status Response and Heartbeat messages.

·         Updated CommProtocol.c, CommProtocol.h, and examples: CANReceive.c, CANSend.c, Heartbeat.c, and StatusRequest.c.

·         Updated Finnish office phone number on the front page.

2.0| 2.0.xx| April 27,

2021

| Olek Bogush| ·         Added support for Axiomatic Wi-Fi to CAN converters.

·         Added Converter Type parameter in Heartbeat

and Status Response messages.

·         Updated Documentation section.

·         Updated CANReceive.c , Heartbeat.c and

StatusRequest.c examples together with

Windows.mk and Linux.mk make files.

1.0A| 1.0.xx| March 2,

2017

| Olek Bogush| ·         In SSP Contents added request to unblock the distribution .zip file in Windows.
1.0| 1.0.xx| October 27, 2016| Olek Bogush| ·         Initial release.

OUR PRODUCTS

• AC/DC Power Supplies
• Actuator Controls/Interfaces
• Automotive Ethernet Interfaces
• Battery Chargers
• CAN Controls, Routers, Repeaters
• CAN/WiFi, CAN/Bluetooth, Routers
• Current/Voltage/PWM Converters
• DC/DC Power Converters
• Engine Temperature Scanners
• Ethernet/CAN Converters, Gateways, Switches
• Fan Drive Controllers
• Gateways, CAN/Modbus, RS-232
• Gyroscopes, Inclinometers
• Hydraulic Valve Controllers
• Inclinometers, Triaxial
• I/O Controls
• LVDT Signal Converters
• Machine Controls
• Modbus, RS-422, RS-485 Controls
• Motor Controls, Inverters
• Power Supplies, DC/DC, AC/DC
• PWM Signal Converters/Isolators
• Resolver Signal Conditioners
• Service Tools
• Signal Conditioners, Converters
• Strain Gauge CAN Controls
• Surge Suppressors

OUR COMPANY
Axiomatic provides electronic machine control components to the off-highway, commercial vehicle, electric vehicle, power generator set, material handling, renewable energy and industrial OEM markets. We innovate with engineered and off-the-shelf machine controls that add value for our customers.

QUALITY DESIGN AND MANUFACTURING
We have an ISO9001:2015 registered design/manufacturing facility in Canada.

WARRANTY, APPLICATION APPROVALS/LIMITATIONS

Axiomatic Technologies Corporation reserves the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. Users should satisfy themselves that the product is suitable for use in the intended application. All our products carry a limited warranty against defects in material and workmanship. Please refer to our Warranty, Application Approvals/Limitations and Return Materials Process at https://www.axiomatic.com/service/.

COMPLIANCE
Product compliance details can be found in the product literature and/or on axiomatic.com. Any inquiries should be sent to sales@axiomatic.com.

SAFE USE
All products should be serviced by Axiomatic. Do not open the product and perform the service yourself

SERVICE
All products to be returned to Axiomatic require a Return Materials Authorization Number (RMA#) from sales@axiomatic.com. Please provide the following information when requesting an RMA number:

• Serial number, part number
• Runtime hours, description of problem
• Wiring set up diagram, application and other comments as needed

DISPOSAL
Axiomatic products are electronic waste. Please follow your local environmental waste and recycling laws, regulations and policies for safe disposal or recycling of electronic waste

CONTACTS
Axiomatic Technologies Corporation 1445 Courtneypark Dr. E. Mississauga, ON CANADA L5T 2E3

• TEL : +1 905 602 9270
• FAX : +1 905 602 9279
• www.axiomatic.com
• sales@axiomatic.com

Axiomatic Technologies Oy Höytämöntie 6 33880 Lempäälä FINLAND

• TEL : +358 103 375 750
• www.axiomatic.com
• salesfinland@axiomatic.com

References

• Axiomatic Technologies Corporation
• Ухост || Веб Хостинг
• Axiomatic Technologies Corporation
• Axiomatic Technologies Corporation
• P65Warnings.ca.gov
• p65warnings.ca.gov./
• Return Policy - Axiomatic Technologies Corporation

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>