HMS NT 100, NT 200, NT 420 User Manual
CAN@net NT 100/200/420
Generic Protocol 2.1 for Gateway Mode V6
SOFTWARE DESIGN GUIDE
4.02.0332.20000 1.7 en-US ENGLISH
Important User Information
Disclaimer
The information in this document is for informational purposes only. Please inform HMS Networks of any
inaccuracies or omissions found in this document. HMS Networks disclaims any responsibility or liability for any
errors that may appear in this document.
HMS Networks reserves the right to modify its products in line with its policy of continuous product development.
The information in this document shall therefore not be construed as a commitment on the part of HMS Networks
and is subject to change without notice. HMS Networks makes no commitment to update or keep current the
information in this document.
The data, examples and illustrations found in this document are included for illustrative purposes and are only
intended to help improve understanding of the functionality and handling of the product. In view of the wide range
of possible applications of the product, and because of the many variables and requirements associated with any
particular implementation, HMS Networks cannot assume responsibility or liability for actual use based on the data,
examples or illustrations included in this document nor for any damages incurred during installation of the product.
Those responsible for the use of the product must acquire sufficient knowledge in order to ensure that the product
is used correctly in their specific application and that the application meets all performance and safety requirements
including any applicable laws, regulations, codes and standards. Further, HMS Networks will under no circumstances
assume liability or responsibility for any problems that may arise as a result from the use of undocumented features
or functional side effects found outside the documented scope of the product. The effects caused by any direct or
indirect use of such aspects of the product are undefined and may include e.g. compatibility issues and stability
issues.
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
Table of Contents
Page
1 User Guide ........................................................................................................................... 3
1.1 Related Documents ................................... ... ... ......... ... .....................................................3
1.2 Document History .. ... ... ......................................................................................... ... ........3
1.3 Trademark Information ................... ... ... ...... ... ... ................................................................ 3
1.4 Conventions............................................ ............ ... ... ......... ............................................. 4
2 TCP Server Function ............................................................................................................ 5
3 ASCII Protocol ...................................................................................................................... 6
3.1 Basic Message Format ............................................................... ... ... ......... ... ..................... 6
3.2 Processing of Messages. ... ......... ................................................................................ ........ 7
3.2.1 TCP Stream Handling .. . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . . . 7
3.2.2 How to Handle Incoming Messages .... .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . 7
3.3 Using ASCII Protocol for Remote Access . ... ........................................................................... 8
3.4 C-API for Customer Specific Expansions............................................................................... . 8
4 Message Types .................................................................................................................... 9
4.1 Message..................................................................................... ... ......... ... ..................... 9
4.2 Cyclic Message ..... ... ... ...... ... .......................................................................................... 10
4.2.1 CYC INIT .... .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . 10
4.2.2 CYC UPDATE ............................ .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . 11
4.2.3 CYC STOP . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . 11
4.3 CAN Commands.............. ......... ... ... ............ .................................................................... 12
4.3.1 Initializing the CAN Controller ..................... .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . 13
4.3.2 Configuring the Filter. . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . 16
4.3.3 Starting the CAN Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . 18
4.3.4 Stopping the CAN Controller . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . 18
4.3.5 Requesting the Status . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . 19
4.4 Device Commands................................................................................... ... ......... ... ... ..... 21
4.4.1 DEV OPMODE ............ ... .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . 21
4.4.2 DEV IDENTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . 21
4.4.3 DEV VERSION ............. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . 21
4.4.4 DEV PROTOCOL . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . 21
4.4.5 DEV INTERFACES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . 22
4.5 Events.................................................... ............ ... ... ......... ... ........................................ 22
4.6 Responses ... ......... ... ......................................................................................... ... ... ...... 22
4.6.1 Positive Response. .. . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . 22
4.6.2 Negative Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . 22
4.6.3 Device Response ..... .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . .. . . . . . . . . . . . 22
4.7 PING REQUEST . ... ......... ... ......................................................................................... ... .. 23
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
5 Example ............................................................................................................................. 24
6 List of Error Codes ............................................................................................................. 25
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
User Guide 3 (26)
1 User Guide
Please read the manual carefully. Make sure you fully understand the manual before using the
product.
To use all features and described commands the latest version of the CAN-Gateway Configurator as well
as the latest firmware of the CAN@net NT must be installed. For documentation of firmware versions
below V6 contact Ixxat support.
1.1 Related Documents
Document
Installation Guide VCI Driver
User Manual CAN@net NT 100/200/420
User Manual CAN-Gateway Configurator
User Manual CAN@net NT C-API
1.2 Document History
Author
HMS
HMS
HMS
HMS
Version
1.0 June 2016
1.1
1.2
1.3
1.4 January 2019
1.5
1.6
1.7
Date
October 2016 Adjusted filter examples in 4.2 CAN commands
July 2017 Added information about CAN@net NT 420
April 2018 Adjusted PING REQUEST and title
March 2019 Layout changes
March 2020 Enhanced description of cyclic transmission, added description of remote mode,
November 2020 Added link to programming example
Description
First release
Minor corrections in chapter 4, added command for cyclic message, updated error
codes
firmware version V6
1.3 Trademark Information
Ixxat®is a registered trademark of HMS Industrial Networks. All other trademarks mentioned in
this document are the property of their respective holders.
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
User Guide 4 (26)
1.4 Conventions
Instructions and results are structured as follows:
► instruction 1
► instruction 2
→ result 1
→ result 2
Lists are structured as follows:
• item 1
• item 2
Bold typeface indicates interactive parts such as connectors and switches on the hardware, or
menus and buttons in a graphical user interface.
This font is used to indicate program code and other
kinds of data input/output such as configuration scripts.
This is a cross-reference within this document: Conventions, p. 4
This is an external link (URL): www.hms-networks.com
This is additional information which may facilitate installation and/or operation.
This instruction must be followed to avoid a risk of reduced functionality and/or damage
to the equipment, or to avoid a network security risk.
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
TCP Server Function
2 TCP Server Function
In the Gateway mode the device is acting as a TCP server and transmits and receives data on the
TCP port that is defined with the CAN-Gateway Configurator. The default TCP port is 19228.
Connection:
• Server exclusively accepts a single connection.
• Additional connection requests are rejected.
• Server exchanges data and commands with the ASCII protocol.
The server receives Ethernet ASCII protocol messages, extracts the original CAN message and
transmits the CAN message to the selected CAN bus. Received CAN messages are packed into the
ASCII protocol and forwarded to the connected Ethernet TCP/IP client. The server also handles
commands.
The device automatically starts the protocol server after power-up. When a connection to the
server is closed or lost, the configuration is restarted if PING is activated, but the CAN connection
is neither stopped nor reset.
5 (26)
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
ASCII Protocol 6 (26)
3 ASCII Protocol
The ASCII protocol is used to pack data (CAN messages) and commands for the transfer over
Ethernet TCP/IP network.
The ASCII-Protocol in version 2.1 supports 6 different message types:
• Messages (both directions)
• CAN Commands (from client to server)
• Device Commands (from client to server)
• Events (from server to client)
• Responses (from server to client)
• Ping Request
Commands have to be confirmed. Before a new command can be transmitted an answer has to
be received.
The ASCII protocol can be used in two ways:
• by implementing the ASCII commands on the host side
• by using the C-API ixcan (reference documentation of the C-API functions is contained in the
API package)
3.1 Basic Message Format
Basic Rules of ASCII Protocol:
• Messages are coded with ASCII characters exclusively.
• Valid characters:
– letters from a to z (no national characters)
– no distinction between upper and lower case
– numbers from 0 to 9
• Messages start with a valid ASCII character and are terminated dependent on the settings in
the CAN-Gateway Configurator with
\r\n, \r, or \n (End-Of-Line).
• Directly after End-Of-Line the next message can follow.
• Messages containing invalid characters are discarded.
• Message contents (e.g. CAN identifier, CAN data) are noted in HEX notation. Other formats
are not supported. HEX specifier (0x...) is omitted.
• ASCII protocol message consists of groups of ASCII characters, each group separated by a
space character (0x20).
• More than one consecutive space characters (0x20) are reduced to a single space character.
• No space characters before and after a CAN message
• The groups of ASCII characters describe different types of messages or commands contained
in the ASCII-Protocol message.
• The single characters of an ASCII-Protocol message are transmitted over the TCP connection
in readable order; beginning with the “message type” group of ASCII characters and ending
with the termination \n.
• Maximum string length (including termination) is 268.
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
ASCII Protocol 7 (26)
3.2 Processing of Messages
3.2.1 TCP Stream Handling
The communication from and to the CAN@net NT is handled as TCP stream. When reading data
from the TCP socket the host might receive or read only parts of a CAN message or a command
response. Since only complete messages can be processed, the host must wait for the remaining
data and then process the complete CAN message or command response. Wether a message is
complete or not, the host identifies based on the end of line termination (dependent on the
operating system and the respective settings in the CAN-Gateway Configurator with \r\n, \r,
or \n).
An programming example that shows how to analyze the received message stream is included in
the CAN-Gateway Configurator download package in C:\Users\Public\Documents\HMS\Ixxat
CAN-Gateway Configurator\Examples\ASCII.
3.2.2 How to Handle Incoming Messages
The communication from and to the device is handled asynchronous.
Example
A CAN status command/response sequence can be interrupted by incoming CAN messages.
tx: CAN 1 STATUS
rx: M 1 CSD 123 02 22 33
rx: M 2 CSD 345 02 55 AA
rx: R CAN 1 ----- 100
This is especially the case when working with more than one CAN controller. The ASCII message
parser on the host side has to take care on that and handle receiving ASCII messages on an event
basis.
The host message parser has to distinguish the following types of messages:
• CAN message, like M 2 CSD 01 C4 97 00 00 00 00 00 00
• Positive response (R ok)
• Negative response (R ERR <error-number> <error-description>)
• Device response, like R CAN CAN
• Events like E 1 BUSOFF
• CAN status response, like R CAN 1 ----- 100
CAN Message
Receiving CAN messages follows the definition of transmitting messages in Message, p. 9.
Example
M 1 CSD 100 55 AA 55 AA
M 2 CED 18FE0201 01 02 03 04 05 06 07 08
CAN@net NT 100/200/420 Software Design Guide
4.02.0332.20000 1.7 en-US
Loading...