TCN-MVB-ACP ACP protocol description

Transcription

1 ACP protocol description Programmer s manual Version 1.18 tcn-mvb-acp_ms_en_118

2 AMiT spol. s r. o. does not provide any warranty concerning the contents of this publication and reserves the right to change the documentation without obligation to inform any body or authority about it. This document can be copied and redistributed under following conditions: 1. The whole text (all pages) must be copied without any changes. 2. All redistributed copies must retain the AMiT, spol. s r. o. copyright notice and any other notices contained in the documentation. 3. This document may not be distributed for purpose making of profit. The names of products and companies used herein can be trademarks or registered trademarks of their respective owners. AMiT is a registered trademark. Copyright (c) 2016, AMiT, spol. s r. o. Producer: AMiT, spol. s r. o. Naskové 1100/3, Praha Technical support: support@amit.cz tcn-mvb-acp_ms_en_118 2/71

3 Contents History of revisions... 5 Related documentation Introduction HW solution System block scheme Interface to 407 processor Interface to host system SW solution Description of MVB module access protocol Description of services Writing the configuration service Reading the configuration service Writing the configuration extended service Reading the configuration extended service Writing the device status service Reading the device status service Reading the list of found devices service Reading the MVB statistics service Clearing the MVB statistics service Writing the ports configuration service Reading the ports configuration service Writing data to the port service Reading data from the port service Writing data to set of ports service Reading data from set of ports service Enabling the port service Disabling the port service Enabling set of ports service Disabling set of ports service Forcing data to the port service Unforcing data from the port service Unforcing all data from traffic store service Writing the ACP/ANM control Reading the ACP/ANM status service Clearing the journal service Reading the journal service Description of services for MD communication (class 2) AMI result codes Reading the station identifier service Writing the station identifier service Reading the routing directories service Writing the routing directories service Reading the TCN messenger status Writing the TCN messenger control Registration of caller and replier functions Cancel previous registration of caller and replier functions /71 tcn-mvb-acp_ms_en_118

4 3.3.9 Reading states of MD instances Writing control of the caller instance Writing control of the replier instance Description of services for bus administration (class 3 and 4) Writing bus administrator configuration service Writing cancel bus administrator configuration service Writing start/stop bus administrator service Reading bus administrator status service Reading bus administrator statistics service Clearing bus administrator statistics service The Description of services for module firmware updating Download control Download status check Firmware data download Get information about device Encoding of data types tcn-mvb-acp_ms_en_118 4/71

5 History of revisions Document name: tcn-mvb-acp_ms_en_118.pdf Version Date Author of change Changes Maštálka O. New document Maštálka O. Correct result codes, add enabling set of ports and disabling set of ports services Maštálka O. Add reading the list of found devices service Maštálka O. Add fields HW and SW name into Reading the configuration service. Add reading the MVB statistics service. Add clearing the MVB statistics service. Correct encoding of data types Maštálka O. Add field T_reply into Writing the configuration service. Add fields Frame_cnt, Frame_err_cnt, Frame_err_a_cnt, Frame_err_b_cnt and Switch_cnt to Reading the MVB statistics service Maštálka O. Updated chapter Maštálka O. Add MD and journal services Maštálka O. Add state machine description in MD services Maštálka O. Add bus administrator services Maštálka O. Add examples of using some services Maštálka O. Chapter 3.1. correct sequential number description Maštálka O. Document revision Maštálka O. Add particular counting of ACP frame length in all services Maštálka O. Correct description of writing control of the replier instance Maštálka O. Correct bus administrator services (chapter 3.4.), added a get information about device configuration frame (chapter 3.5.4) Dočekal A. Chapter 3.5.4, DEV_STATUS updated, information about invalid device runtime status added Maštálka O. Chapter 3.4.1, add service load of list of devices for MD communication. Chapter 3.4.5, add counters to bus administrator statistics Maštálka O. Chapter 3.1., add example of data stuffing and framing. Chapter 3.3.6, add MICAS system group compatibility Tomáš M. Add Chapters 3.2.3, Related documentation 5/71 tcn-mvb-acp_ms_en_118

6 1. Introduction Module RM-MVB10/1x is a communication interface between MVB line and customer hardware. The module mediates the all MVB services. Module software, depending on its type, provides for MVB TCN process data and message services as well as bus administration. This document describes the module software interface which provides to TCN MVB the process data services. Piggy back technique Built-in into third party equipments Parallel / serial connection to host CPU Possible support of all MVB classes Possible bus administration Possibility of TCN messenger Secured communication protocol with host CPU Simple implementation of protocol in host CPU tcn-mvb-acp_ms_en_118 6/71

7 2. HW solution 2.1. System block scheme 407 Altera Host pipe UART emulation Fig. 1 - System block scheme 2.2. Interface to 407 processor Interface to 407 processor is designed as proprietary pipe over SPI bus. Description of this interface is not subject of this document Interface to host system Interface to host is realized by UART, choice of which depends on applicator. Variants considered so far takes into account the asynchronous UART interface (RXD, TXD, handshaking), simplified emulated UART over parallel bus and emulated UART 16C550A over LPC bus. Detail description of these interfaces is beyond the scope of this document. 7/71 tcn-mvb-acp_ms_en_118

8 3. SW solution 3.1. Description of MVB module access protocol Protocol for accessing MVB via UART is frame oriented. The frame is preambled by pair of characters data link escape followed by start of text (DLE STX) and terminated by pair of characters data link escape followed by end of text (DLE ETX). Presence of character DLE as data is realized by its twinning. Codes of control characters was chosen from ASCII table (STX = 0x02, ETX = 0x03, DLE = 0x10). Example of stuffing and framing of data is in the following table: Data to be sent: A DLE B ETX DLE STX E After stuffing and framing: DLE STX A DLE DLE B ETX DLE DLE STX E DLE ETX Note: Frame is composed from 6-byte header and data. On the frame end is stored the frame checksum, calculated under CRC16-CCITT algorithm. Minimum frame length is 8 bytes, maximum frame length is 508 bytes. of initial (DLE STX) preamble and terminating (DLE ETX) delimiter is not included in frame length nor in frame header. Frame is structured as follows: U16 Frame length incl. header and CRC (minimum 8 bytes) / response ( r ) Service Ch8 Service type Command/Status U8/Ch8 Command/process return code Frame data When a twinning DLE character appears, it is not part of frame (not included in frame length) and must be removed when receiving data. CRC is calculated from all data, starting with frame length and last data byte before CRC field. CRC16-CCITT uses a x 16 + x 12 + x polynomial Initial CRC value before calculation is equal to 0xFFFF. Note: Protocol is of request/response type, i.e. each service is confirmed. Modification (write) services are coded by upper case letter, reading services are coded by lower case letter. All frame elements are aligned to multiples of their length and moreover, each frame is rounded to even number of bytes. tcn-mvb-acp_ms_en_118 8/71

9 All multi-byte numeric frame components are little endian ordered. Little endian ordering relates only to frame items. Port data (datasets) are transmitted like byte-stream without endian conversion. It s up to application to fill the dataset properly, in accordance with data type specification in TCN standard (TCN standard codes all multi-byte numerical types with big endian order). Sequential number identifies the given session; it s incremented by modulo 256 for each new outgoing session, correspond response includes a sequential number identical with request. If processing of data fails, then the reply frame does not contain any data except of return code. Return codes are as follows: Return code Value amit_mvb_ok 0 All is OK amit_mvb_failure 1 Unspecified failure Communication return codes amit_mvb_res_bad_size 2 Incorrect frame length amit_mvb_res_send_err 3 Frame sending error amit_mvb_res_tmo_err 4 Session timeout (while waiting for response) amit_mvb_rem_canc_err 5 Session cancelled by partner amit_mvb_rem_not_found 6 Session not found at partner amit_mvb_rem_no_free 7 No free resources for incoming request at partner amit_mvb_rem_dupl 8 Previous session was not yet finished amit_mvb_rem_ usr_unreg 9 User not registered at partner amit_mvb_rem_int_err 10 Internal error at partner Application return codes amit_mvb_rem_no_free 30 No free resources in remote application (instance, memory) amit_mvb_rem_ srv_unreg 31 Service not registered amit_mvb_rem_ srv_fail 32 Service not executed amit_mvb_rem_bad_len 33 Wrong length of received datagram amit_mvb_rem_bad_pars 34 Incorrect parameters in received datagram amit_mvb_rem_lp_err 35 LPI/LPA access error amit_mvb_rem_ls_err 36 Supervision interface error amit_mvb_rem_port_bad_cfg 37 Incorrect port configuration amit_mvb_rem_ports_many 38 Too many ports amit_mvb_rem_sys_no_psv 39 Passive state of system is required amit_mvb_dwn_err_init 52 Initialization of firmware loading error amit_mvb_dwn_err_erase 53 Memory erase error amit_mvb_dwn_err_wrt 54 Data write error amit_mvb_dwn_err_fw 55 New firmware data are not valid, firmware refused amit_mvb_dwn_err_chksm 56 Invalid checksum amit_mvb_dwn_err_len 57 Invalid data length amit_mvb_dwn_err_sys 58 System download error 9/71 tcn-mvb-acp_ms_en_118

10 3.2. Description of services Software of RM-MVB10/1x module provides a set of services through which the host CPU can access MVB ports, supervise MVB bus, control ACP/ANM protocol and read its status / diagnostic. Following services are available: Service Code Chapter Writing the configuration service C Reading the configuration service c Writing the configuration extended service N Reading the configuration extended service n Writing the device status service D Reading the device status service d Reading the list of found devices service I Reading the MVB statistics service s Clearing the MVB statistics service T Writing the ports configuration service P Reading the ports configuration service P Writing data to the port service W Reading data from the port service r Writing data to set of ports service G Reading data from set of ports service g Enabling the port service E Disabling the port service U Enabling set of ports service S Disabling set of ports service R Forcing data to the port service F Unforcing data from the port service X Unforcing all data from traffic store service A Writing the ACP/ANM control! Reading the ACP/ANM status service? Clearing the journal service J Reading the journal service j Writing the configuration service Writing the configuration service provides setting the device address and lines configuration. U16 Frame length (12 bytes) Service Ch8 Writing the configuration ( C ) Sequence number U8 Session sequential number Configuration U16 Device configuration tcn-mvb-acp_ms_en_118 10/71

11 T_Reply U16 Reply timeout 0 default reply (42.7 μs) 1 ¼ reply (10.7 μs) 2 ½ reply (21.4 μs) 3 ¾ reply (32 μs) 4 default reply (42.7 μs) 5 1 ¼ reply (53.4 μs) 6 1 ½ reply (64 μs) 7 1 ¾ reply (74.7 μs) 8 double reply (85.4 μs) The configuration item has following format: Bit 15 Bit 14 Bit Bit 0 11 Line A Line B MD Priority Device address MVB A, B lines: Line A Line B 0 0 Passive state, device reconfiguration (initial device state) 0 1 Reserved 1 0 Reserved 1 1 Regular state, operation on redundant MVB lines MD priority (for devices of class 2 and higher only): Bit 13 Bit Reserved 0 1 Messages low priority 1 0 Messages high priority 1 1 Reserved Note: Example: U16 Frame length (8 bytes) Service Ch8 Writing the configuration ( C ) Status U8 Return code of processing Device address 0 means that no change of device address is requested. Setting of device address is possible only in passive state. It is necessary to put the device into passive state first in case of request for device address change. Device address = 16, message low priority, default reply timeout. Hexadump of request is: 10:02:0C:00:63:43:00:01 10:10:10:10:00:00:71:B4 10:03 Hexadump of response is: 10:02:08:00:72:43:00:01 93:F8:10:03 11/71 tcn-mvb-acp_ms_en_118

12 3.2.2 Reading the configuration service Reading the configuration service provides reading of current device configuration and identification of MVB hardware and software. Device address 0 means, that no address has been set up yet. U16 Frame length (8 bytes) Service Ch8 Reading the configuration ( c ) U16 Frame length (74 bytes) Service Ch8 Reading the configuration ( c ) Status U8 Return code of processing Configuration U16 Device configuration HW name String32 NULL terminated string with identification of MVB hardware and its version SW name String32 NULL terminated string with identification of MVB software and its version The Device configuration item has identical format with the same item in chapter Writing the configuration service. Example: Hexadump of request: 10:02:08:00:63:63:00:02 25:23:10:03 Hexadump of response: 10:02:4A:00:72:63:00:02 10:10:10:10:52:4D:2D:4D 56:42:31:30:2F:31:31:20 31:00:00:00:00:00:00:00 00:00:00:00:00:00:00:00 00:00:00:00:41:4D:69:54 20:4D:56:42:20:6C:69:62 2D:56:31:2E:30:32:2D:31 31:2E:31:31:2E:32:30:31 33:00:00:00:0A:1A:10:03 Device address=16, message low priority, HW name= RM-MVB10/11 1 SW name= AMiT MVB lib-v tcn-mvb-acp_ms_en_118 12/71

13 3.2.3 Writing the configuration extended service Writing the configuration extended service provides setting the device address, lines configuration and HW configuration. U16 Frame length (16 bytes) Service Ch8 Writing the configuration ( N ) Sequence number U8 Session sequential number Configuration U16 Device configuration T_Reply U16 Reply timeout 0 default reply (42.7 μs) 1 ¼ reply (10.7 μs) 2 ½ reply (21.4 μs) 3 ¾ reply (32 μs) 4 default reply (42.7 μs) 5 1 ¼ reply (53.4 μs) 6 1 ½ reply (64 μs) 7 1 ¾ reply (74.7 μs) 8 double reply (85.4 μs) HW interface cfg U8 0 default configuration without optical control 1 configuration with optical control Reserved U8 Reserved Reserved U16 Reserved The configuration item is specified in chapter Writing the configuration service. Note: U16 Frame length (8 bytes) Service Ch8 Writing the configuration ( N ) Status U8 Return code of processing Device address 0 means that no change of device address is requested. Setting of device address is possible only in passive state. It is necessary to put the device into passive state first in case of request for device address change. 13/71 tcn-mvb-acp_ms_en_118

14 3.2.4 Reading the configuration extended service Reading the configuration extended service provides reading of current device configuration and identification of MVB hardware and software. Device address 0 means, that no address has been set up yet. U16 Frame length (8 bytes) Service Ch8 Reading the configuration ( n ) U16 Frame length (76 bytes) Service Ch8 Reading the configuration ( n ) Status U8 Return code of processing Configuration U16 Device configuration HW name String32 NULL terminated string with identification of MVB hardware and its version SW name String32 NULL terminated string with identification of MVB software and its version HW interface cfg U8 0 default configuration without optical control 1 configuration with optical control Reserved U8 Reserved The Device configuration item has identical format with the same item in chapter Writing the configuration service Writing the device status service Writing the device status service allows to set the device status. This status is then sent to other devices. U16 Frame length (10 bytes) Service Ch8 Writing the device status ( D ) tcn-mvb-acp_ms_en_118 14/71

15 Note: Device status U16 Device status When setting the device status, only SDD, DNR and SER bits can be affected. The other bits are set automatically by device itself. U16 Frame length (8 bytes) Service Ch8 Writing the device status ( D ) Status U8 Return code of processing Reading the device status service Reading the device status service allows to read status of device, identified by its device address. U16 Frame length (10 bytes) Service Ch8 Reading the device status ( d ) Device address U16 Device address Format of Device address item is as follows: Bit Bit 0 11 Reserved Device address U16 Frame length (12 bytes) Service Ch8 Reading the device status ( d ) 15/71 tcn-mvb-acp_ms_en_118

16 Note: Status U8 Return code of processing Device status U16 Device status Freshness U16 Time, elapsed from last transmission of status from given device [ms] Device status of device itself is possible to read only after it has been sent on bus Reading the list of found devices service Through reading the list of found devices service can be read the current list of found devices on the MVB bus. The list includes device address and device status for each found MVB device. By single frame can be read list of maximum 124 devices; in case that more devices are present on the MVB bus, it s possible to read other MVB devices by entering of the appropriate set index. U16 Frame length (10 bytes) Service Ch8 Reading the list of found devices ( l = 0x6C) Set index U16 0 = set of first 124 devices, 1 = set of second 124 devices, U16 Frame length (8 + nr_devices * 4 + 4) Service Ch8 Reading the list of found devices ( l = 0x6C) Status U8 Return code of processing Number of devices U16 Number of devices (maximum 124) Device descriptor 1 U32 Descriptor of device No. 1 Device descriptor 2 U32 Descriptor of device No. 2 Device descriptor n U32 Descriptor of device No. n Number of additional devices U16 Number of devices in following sets, that did not fit into frame tcn-mvb-acp_ms_en_118 16/71

17 Device descriptor: Reading the MVB statistics service Bit Bit 0 15 Device status Device address Reading the MVB statistics provides reading MVB statistics and diagnostics counters. U16 Frame length (8 bytes) Service Ch8 Reading the MVB statistics ( s ) DLE ETX U16 End Of Frame (0x10, 0x03) DLE STX U16 Start Of Frame (0x10, 0x02) U16 Frame length (104 bytes) Service Ch8 Reading the MVB statistics ( s ) Status U8 Return code of processing state Bus_timeout_cnt U32 Bus timeout counter Reply_timeout_cnt U32 Reply timeout counter Frame_lost_cnt U32 Frame lost counter Frame_cnt U32 Frame counter Frame_err_cnt U32 Counter of erroneous frames Frame_err_a_cnt U32 Counter of erroneous frames on line A Frame_err_b_cnt U32 Counter of erroneous frames on line B Switch_cnt U32 Counter of line switches Received master frame statistics Valid_cnt U32 Counter of valid frames Dupl_cnt U32 Counter of duplicated frames Error_cnt U32 Counter of error frames Manch_viol_cnt U32 Counter of manchester violation errors Bus_not_idle_cnt U32 Counter of bus not idles Over_balance_cnt U32 Counter of over balance errors Signal_err_cnt U32 Counter of signal quality errors Crc_err_cnt U32 Counter of CRC errors Received slave frame statistics Valid_cnt U32 Counter of valid frames Dupl_cnt U32 Counter of duplicated frames Error_cnt U32 Counter of error frames Manch_viol_cnt U32 Counter of manchester violation errors 17/71 tcn-mvb-acp_ms_en_118

18 Bus_not_idle_cnt U32 Counter of bus not idles Over_balance_cnt U32 Counter of over balance errors Signal_err_cnt U32 Counter of signal quality errors Crc_err_cnt U32 Counter of CRC errors Clearing the MVB statistics service Clearing the MVB statistics service provides reseting MVB statistics and diagnostics counters. U16 Frame length (8 bytes) Service Ch8 Clearing the MVB statistics ( T ) U16 Frame length (8 bytes) Service Ch8 Clearing the MVB statistics ( T ) Status U8 Return code of processing Writing the ports configuration service By writing the ports configuration service is possible to configure addresses, lengths and type of ports. By single frame can be configured up to 124 ports; when configuration of more ports is required, then is necessary to call this service more times. If the port has been configured formerly, new configuration replaces the original one (port is reconfigured). Each port can be configured as source, target (sink) or source and sink simultaneously. Ports can be configured only in passive state of MVB. tcn-mvb-acp_ms_en_118 18/71

19 U16 Frame length (8 + nr_ports * bytes) Service Ch8 Writing the ports configuration ( P ) Number of ports U16 Number of ports involved in configuration (maximum 124) Port descriptor 1 U32 Descriptor of port No. 1 Port descriptor 2 U32 Descriptor of port No. 2 Port descriptor n U32 Descriptor of port No n. Port descriptor: Fcode: Bit Bit 17 Bit 16 Bit Bit 0 11 Reserved Src Snk Fcode Port address Value Port length (bits) Note: U16 Frame length (10 bytes) Service Ch8 Writing the ports configuration ( P ) Status U8 Return code of processing Number of ports U16 Number of processed ports After configuration port remains passive. Data can be written into passive source port, but they are not transmitted on bus. From passive sink port data can be read, but they are not received from bus. Port is enabled by service Enabling the port. It allows application to ensure, that only valid data prepared in advance are sent/received on/from the bus (important namely with device reconfiguration). Sink port and source port can be written using one descriptor or two descriptors placed just behind. 19/71 tcn-mvb-acp_ms_en_118

20 Example: Configuration of 6 ports: 1. Port source, address = 220h, fcode = 3 2. Port source, address = 221h, fcode = 4 3. Port source, address = 222h, fcode = 2 4. Port sink, address = 300h, fcode = 1 5. Port sink, address = 301h, fcode = 3 6. Port sink, address = 302h, fcode = 0 Hexadump of request is: 10:02:22:00:63:50:00:03 06:00:20:32:02:00:21:42 02:00:22:22:02:00:00:13 01:00:01:33:01:00:02:03 01:00:74:9B:10:03 Hexadump of response is: 10:02:0A:00:72:50:00:03 06:00:5A:88:10: Reading the ports configuration service Through reading the ports configuration service can be read the current configuration of all ports. By single frame can be read configuration of maximum 124 ports; in case that more ports is configured, it s possible to read other ports by entering of the appropriate set index. U16 Frame length (10 bytes) Service Ch8 Reading the ports configuration ( p ) Set index U16 0 = set of first 124 ports, 1 = set of second 124 ports, U16 Frame length (8 + nr_ports * bytes) Service Ch8 Reading the ports configuration ( p ) Status U8 Return code of processing Number of ports U16 Number of ports in set (maximum 124) Port descriptor 1 U32 Descriptor of port No. 1 Port descriptor 2 U32 Descriptor of port No. 2 Port descriptor n U32 Descriptor of port No. N Number of additional ports U16 Number of ports in following sets, that did not fit into frame tcn-mvb-acp_ms_en_118 20/71

21 Port descriptor: Bit Bit 21 Bit 20 Bit 19 Bit 18 Bit 17 Bit 16 Bit Bit 0 11 Reserved Src Snk Twc Frc Src Snk Fcode Port address Current configuration Static configuration Note: The current port configuration is given by combination of following flags: Flag Description Src Source Source port Snk Sink Destination port Twc Transfer with checksum Transfer of process data with checksum (for debugging only) Frc Force In the port is stored the replacement data (see chapter Forcing data to the port service ) When neither Src nor Snk flags are set at dynamic configuration, the port is passive Writing data to the port service The service provides writing data into source port. U16 Frame length (8 + datset_length + 2) Service Ch8 Writing data to the port ( W ) Port identification U16 Port length (fcode) and address Dataset Port contents Port identification: Bit Bit 0 11 Fcode Port address Note: U16 Frame length (8 bytes) Service Ch8 Writing data to the port ( W ) Status U8 Return code of processing It is not possible to write data into sink port, alternatively into port which is not configured. 21/71 tcn-mvb-acp_ms_en_118

22 The port fcode must agree with previous configuration. When data is entered into port, it is not passed immediately onto bus: the port must be first enabled (see chapter Enabling port service) and data is sent when the port is asked for transfer by master. When writing data into port the force can be eventually applied (see chapter Forcing data to the port service ) Reading data from the port service By reading data from the port service is read the appropriate dataset from port. U16 Frame length (10 bytes) Service Ch8 Reading data from the port ( r ) Port identification U16 Port length (fcode) and address Note: U16 Frame length (8 + dataset_length + 2 bytes) Service Ch8 Reading data from the port ( r ) Status U8 Return code of processing Freshness U16 Time, elapsed from last data transmission to port [ms] Dataset Port contents Data cannot be read from port, which is not configured. If the port is configured as source and at the same time as sink, data is read from sink port part. When reading data from port the forcing can be eventually applied (see chapter Forcing data to the port service ). tcn-mvb-acp_ms_en_118 22/71

23 Writing data to set of ports service By writing data to set of ports service can be data written simultaneously into more source ports. U16 Frame length (8 + nr_ports * 2 + nr_ports * dataset_length + 2 bytes) Service Ch8 Writing data to set of ports ( G ) Number of ports U16 Number of ports (maximum 124 for 16-bit ports) Identification of 1. port U16 Port No. 1 length (fcode) and address Identification of 2. port U16 Port No. 2 length (fcode) and address Identification of n. port U16 Port No. n length (fcode) and address Dataset 1 Contents of 1. port Dataset 2 Contents of 2. port Dataset n Contents of n. port Note: U16 Frame length (8 bytes) Service Ch8 Writing data to set of ports ( G ) Status U8 Return code of processing Data consistency is guaranteed only within contents of single port (dataset), but not between individual ports. Dataset is transferred always as a whole Reading data from set of ports service Reading data from set of ports service is used for reading more dataset from ports. U16 Frame length (8 + nr_ports * bytes) Service Ch8 Reading data from set of ports ( g ) 23/71 tcn-mvb-acp_ms_en_118

24 Number of ports U16 Number of ports (maximum 124 for 16-bit ports) Identification of 1. U16 Port No. 1 length (fcode) and address port Identification of 2. U16 Port No. 2 length (fcode) and address port Identification of n. U16 Port No. n length (fcode) and address port Note: U16 Frame length (8 + nr_ports * (2 + dataset_length) + 2 bytes) Service Ch8 Reading data from set of ports ( g ) Status U8 Return code of processing state Number of ports U16 Number of read ports (maximum 124 for 16-bit ports) Freshness 1 U16 Time, elapsed from last data transmission to 1. port [ms] Dataset 1 Contents of 1. Port Freshness 2 U16 Time, elapsed from last data transmission to 2. port [ms] Dataset 2 Contents of 2. Port Freshness n U16 Time, elapsed from last data transmission to n. port [ms] Dataset n Contents of n. port If the datasets are longer than maximum data length of frame, less ports is read Enabling the port service By enabling the port service is enabled transmitting/receiving data from/to port to/from bus. U16 Frame length (10 bytes) tcn-mvb-acp_ms_en_118 24/71

25 Service Ch8 Enabling the port ( E ) Port address U16 Port address Note: U16 Frame length (8 bytes) Service Ch8 Enabling the port ( E ) Status U8 Return code of processing Recommended procedure for application is: first of all write data into source port through Write data to port service and after then enable transmitting of data from port. By this way is guaranteed validity of dataset which is transmitted to bus Disabling the port service Disabling the port service is disabled transmitting/receiving data from/to port to/from bus(es). U16 Frame length (10 bytes) Service Ch8 Disabling the port ( U ) Port address U16 Port address U16 Frame length (8 bytes) Service Ch8 Disabling the port ( U ) Status U8 Return code of processing state 25/71 tcn-mvb-acp_ms_en_118

26 Note: When application stops to produce data to certain ports (for instance due to change of operation state), it s recommended to disable these ports. By this is guaranteed, that data in sink ports become of outdated for potential consumers Enabling set of ports service This service allows enabling more ports at once. For more information please refer to the Enabling the port service. U16 Frame length (8 + nr_ports * bytes) Service Ch8 Enabling set of ports ( S ) Number of ports U16 Number of ports (maximum 124) Port address 1 U16 Address of 1. port Port address 2 U16 Address of 2. port Port address n U16 Address of n. port U16 Frame length (8 bytes) Service Ch8 Enabling set of ports ( S ) Status U8 Return code of processing state Disabling set of ports service This service allows disabling more ports at once. For more information please refer to the Enabling the port service. U16 Frame length (8 + nr_ports * bytes) tcn-mvb-acp_ms_en_118 26/71

27 Service Ch8 Disabling set of ports ( R ) Number of ports U16 Number of ports (maximum 124) Port address 1 U16 Address of 1. port Port address 2 U16 Address of 2. port Port address n U16 Address of n. port U16 Frame length (8 bytes) Service Ch8 Disabling set of ports ( R ) Status U8 Return code of processing state Forcing data to the port service Forcing data to the port service allows transmitted (from source port) or received (by sink port) a substitute data instead of real data. U16 Frame length (8 + dataset_length * bytes) Service Ch8 Forcing data to the port ( F ) Port identification U16 Port length (fcode) and address Force data Substitute data Force mask Substitute data mask U16 Frame length (8 bytes) 27/71 tcn-mvb-acp_ms_en_118

28 Note: Service Ch8 Forcing data to the port ( F ) Status U8 Return code of processing If a substitute data are stored in port, then force flag for corresponding port dynamic configuration and frc flag in device status are set Unforcing data from the port service By unforcing data from the port service are removed the substitute data from port. U16 Frame length (8 + dataset_length + 2 bytes) Service Ch8 Unforcing data from the port ( X ) Port identification U16 Port length (fcode) and address Unforce mask Mask for force data cancelling Note: U16 Frame length (8 bytes) Service Ch8 Unforcing data from the port ( X ) Status U8 Return code of processing When force is cancelled for source port, the substitute data are not removed immediately, but there are overwritten by new real data from application Unforcing all data from traffic store service Unforcing all data from traffic store service removes the force data from all ports in traffic store. U16 Frame length (8 bytes) tcn-mvb-acp_ms_en_118 28/71

29 Service Ch8 Unforcing all data from traffic store ( A ) U16 Frame length (8 bytes) Service Ch8 Unforcing all data from traffic store ( A ) Status U8 Return code of processing state Writing the ACP/ANM control Writing the ACP/ANM control provides settings of timeouts and reseting of statistics counters. U16 Frame length (20 bytes) Service Ch8 Writing the ACP/ANM control (! ) Command mask U32 Mask of commands to be executed: 0x1 configuration of timeouts 0x2 reset of statistics of ANM protocol 0x4 reset of statistics of ACP protocol Alive timeout U32 Timeout of waiting for duplicated frame [ms] Session timeout U32 Timeout of waiting for the end of the session [ms] U16 Frame length (12 bytes) Service Ch8 Writing the ACP/ANM control (! ) Status U8 Return code of processing state 29/71 tcn-mvb-acp_ms_en_118

30 Note: Timeouts result U8 Result of configuration timeouts ANM result U8 Result of reseting ANM protocol statistics ACP result U8 Result of reseting ACP protocol statistics Reserved U8 Reserved It is recommended to set up alive timeout as session timeout * Reading the ACP/ANM status service Reading the ACP/ANM status provides reading of the library version and reading of ACP/ANM statistics and diagnostics counters. U16 Frame length (8 bytes) Service Ch8 Reading the ACP/ANM status (? ) U16 Frame length (172 bytes) Service Ch8 Reading the ACP/ANM status (? ) Status U8 Return code of processing state Manufacturer String32 NULL terminated string with name of manufacturer of device Timestamp U32 UNIX timestamp of ACP/ANM library release Version U16 Version of the ACP/ANM library release Revision U16 Revision of the ACP/ANM library release Build U16 Build of the ACP/ANM library release Reserved U16 Reserved ANM_tx_cnt U32 Counter of transmit ANM responses ANM_tx_rfs_cnt U32 Counter of refused ANM responses ANM_rx_cnt U32 Counter of received ANM requests ANM_rx_rfs_cnt U32 Counter of refused ANM requests ACP_alive_tmo U32 Timeout of waiting for duplicated frame [ms] ACP_session_tmo U32 Timeout of waiting for the end of the session [ms] ACP_tx_cnt U32 Counter of transmit ACP datagrams tcn-mvb-acp_ms_en_118 30/71

31 ACP_tx_err_cnt U32 Counter of ACP datagrams which were impossible to transmit ACP_rx_cnt U32 Counter of received ACP datagrams ACP_rx_err_cnt U32 Counter of ACP datagrams received with error ALI_tx_cnt U32 Counter of transmit ALI frames ALI_tx_cnt_err U32 Counter of ALI frames which were impossible to transmit ALI_rx_cnt U32 Counter of received ALI frames ALI_rx_err_cnt U32 Counter of ALI frames received with error ALI_rx_no_free_cnt U32 Counter of no free buffers ALI_rx_out_stx_cnt U32 Counter of out sequence DLE STX ALI_rx_out_etx_cnt U32 Counter of out sequence DLE ETX ALI_rx_out_dle_cnt U32 Counter of unknown DLE sequences ALI_rx_bad_len_cnt U32 Counter of received frames with incorrect length ALI_rx_bad_crc_cnt U32 Counter of frames with incorrect CRC ALI_rx_que_err_cnt U32 Counter of queue errors ASISI_tx_cnt U32 Counter of transmit ASISI frames ASISI_tx_cnt_err U32 Counter of ASISI frames which were impossible to transmit ASISI_rx_cnt U32 Counter of received ASISI frames ASISI_rx_err_cnt U32 Counter of ASISI frames received with error ASISI_rx_dma_cnt U32 Counter of received ASISI frames with DMA error ASISI_rx_to_cnt U32 Counter of ASISI frames with TO error ASISI_rx_que_err_cnt U32 Counter of ASISI queue errors ASISI_rx_bad_hdr_cnt U32 Counter of ASISI frames with incorrect header ASISI_bad_nss_cnt U32 Counter of incorrect NSS states Clearing the journal service Clearing the journal service provides clearing of the main and extra journal. After calling this service the main and extra journal are empty. U16 Frame length (8 bytes) Service Ch8 Clearing the journal service ( J ) 31/71 tcn-mvb-acp_ms_en_118

32 U16 Frame length (8 bytes) Service Ch8 Clearing the journal service ( J ) Status U8 Return code of processing state Reading the journal service Reading the journal service provides reading of parameters, reading of records identified by start id and end id and reading of last records of the journal. It is possible to read maximum of 4 journal records by one command. Common request format is as follows: U16 Frame length (min. 10 bytes) Service Ch8 Reading the journal service ( j ) Command U8 1 reading of journal parameters 2 reading of journal records identified by start_id and end_id 3 reading of last journal records Reserved U8 Reserved Journal_ U8 of the journal: 0 main journal 1 extra journal Parameters depending on the type of command Reading of journal parameters request format is as follows: U16 Frame length (10 bytes) Service Ch8 Reading the journal service ( j ) Command U8 1 reading of journal parameters Reserved U8 Reserved Journal_ U8 of the journal: 0 main journal 1 extra journal tcn-mvb-acp_ms_en_118 32/71

33 Reading of journal parameters response format is as follows: U16 Frame length (16 bytes) Service Ch8 Reading the journal service ( j ) Status U8 Return code of processing state Total length U16 Total length of the journal Current length U16 The current number of records in the journal Oldest ID U16 The unique identification of the oldest record Newest ID U16 The unique identification of the newest record Reading of the journal records identified by start id and end id request format: U16 Frame length (10 bytes) Service Ch8 Reading the journal service ( j ) Command U8 2 reading of journal records identified by start_id and end_id Reserved U8 Reserved Journal_ U8 of the journal: 0 main journal 1 extra journal Start ID U16 Unique identification of the first record to be read End ID U16 Unique identification of the last record to be read Reading of the journal records response format is as follows: U16 Frame length (10 + nr_records * bytes) Service Ch8 Reading the journal service ( j ) Status U8 Return code of processing state Records number U32 Number of journal records in the frame Time stamp secs 1 U32 UTC number of seconds of first record 33/71 tcn-mvb-acp_ms_en_118

34 Time stamp ticks 1 U16 Number of ticks (1/65536s) of first record Reserved 1 U16 Reserved File name 1 String16 FILE of the first record Line number 1 U16 LINE of the first record Reserved 1 U8 Reserved Event type 1 U8 of the event of the first record 0 information 1 warning 2 error Event description 1 String78 Event description of the first record Reserved 1 U16 Reserved Time stamp secs 2 U32 UTC number of seconds of second record Time stamp ticks 2 U16 Number of ticks (1/65536s) of second record Reserved 2 U16 Reserved File name 2 String16 FILE of the second record Line number 2 U16 LINE of the second record Reserved 2 U8 Reserved Event type 2 U8 of the event of the second record 0 information 1 warning 2 error Event description 2 String78 Event description of the second record Reserved 2 U16 Reserved Reading of the last journal records request format: U16 Frame length (10 bytes) Service Ch8 Reading the journal service ( j ) Command U8 3 reading of last journal records Reserved U8 Reserved Journal_ U8 of the journal: 0 main journal 1 extra journal Number of last U16 Number of last records records The response format is the same as in reading journal records identified by ids. tcn-mvb-acp_ms_en_118 34/71

35 3.3. Description of services for MD communication (class 2) AMI result codes Return codes are as follows: Return code Standard codes am_ok am_failure am_bus_err am_rem_conn_ovf am_conn_tmo_err am_send_tmo_err am_reply_tmo_err am_alive_tmo_err am_loc_no_mem_err am_rem_canc_err am_already_used am_no_reply_exp_err am_nr_of_conv_ovf am_reply_len_ovf am_dupl_conv_err am_no_ready_inst_err am_call_len_ovf am_unknown_dest_err am_inaug_err am_try_later_err am_gw_ori_reg_err am_repeat_tmo_err am_try_later_alive_err User codes am_not_init am_already_init am_int_fatal_err am_descr_not_init am_bus_unknw_type am_bus_wtb_dupl am_bus_lm_err am_route_dir_err am_tx_pool_empty am_rx_pool_empty Errors on local station am_loc_next_not_found am_loc_topo_cnt_err am_loc_not_node am_loc_rout_fct_nset am_loc_sta_next_err am_loc_fct_next_err am_loc_sta_not_found Value 0 all is OK 1 unspecified failure 2 no bus transmission possible 3 too many incoming connections 4 connect request not answered 5 send timeout (connect was ok) 6 session timeout 7 no complete message received 8 not enough memory or timers 10 canceled by partner 11 same operation already done 13 no such reply expected error 14 too many calls requested 15 reply message too long 16 duplicated conversation error 18 no ready instance error 20 call message too long 21 unknown destination address 22 train inauguration occurred 23 the request shall be repeated after send timeout 26 origin is not registered in router 27 the conversation was not setup (repeat timeout) 29 the request shall be repeated after send timeout, maximum is alive timeout 60 interface is not initialized 61 interface is already initialized 62 corrupted internal structures 63 network descriptor is not initialized 64 unknown or unsupported bus type 65 duplicated train bus 66 error on LMI or LMA 67 error while access routing directories 68 transmit packet pool is empty 69 receive packet pool is empty 71 next_station (router) not found in station directory 72 Incorrect combination of address and topo_counter 73 station is not node (it is not connected WTB) 74 router function is not set 75 incorrect combination of final station and router 76 incorrect combination of function and router 79 station not found in station directory 35/71 tcn-mvb-acp_ms_en_118

36 Return code am_loc_fct_not_found am_loc_pck_unknw am_loc_pck_bad_len am_loc_pck_bad am_loc_pck_no_state Errors on remote station am_rem_next_not_found am_rem_topo_cnt_err am_rem_not_node am_rem_rout_fct_nset am_rem_sta_next_err am_rem_fct_next_err am_rem_sta_not_found am_rem_fct_not_found am_rem_pck_unknw am_rem_pck_bad_len am_rem_data_size_ovr am_rem_data_size_less am_rem_pck_bad am_rem_pck_no_state Errors on network layer am_return_path_bad am_bad_net_header AMI input errors am_bad_params Errors on transport layer am_conv_not_found am_invalid_event am_no_free_event Errors on session layer am_sta_id_not_set am_sta_id_bad am_fct_reg_too_many am_fct_unreg_caller am_fct_unreg_replier am_fct_not_manager am_fct_add_fundi_err am_fct_already_def am_dir_write_err am_dir_delete_err am_dir_entrs_more Value 80 function not found in function directory 81 unknown or unsupported packet type 82 incorrect packet length 85 incorrect data in packet 87 no state for incoming packet 89 next_station (router) not found in station directory 90 Incorrect combination of address and topo_counter 91 station is not node (it is not connected WTB) 92 router function is not set 93 incorrect combination of final station and router 94 incorrect combination of function and router 97 station not found in station directory 98 function not found in function directory 99 unknown or unsupported packet type 100 incorrect packet length 101 length of receive data exceeds message length 102 message exceeds length of receive data 103 incorrect data in packet 105 no state for incoming packet 110 test of packet return path fails 111 incorrect network packet header 112 incorrect input parameters to AMI function 115 conversation not found 116 incorrect or unsupported event 117 no free event 120 station id has not yet assigned to this station 121 incorrect identification of station 122 too many registered functions 123 no caller is registered to given function 124 no replier is registered to given function 125 only manager function can use system addressing 126 error while adding function into function directory 127 function is defined on another station 128 error while writing into routing directories 129 some entries were not deleted from directory 130 not all entries were read from directory tcn-mvb-acp_ms_en_118 36/71

37 Following services are available: Service Code Chapter Reading the station identifier service 0x Writing the station identifier service 0x Reading the routing directories service 0x Writing the routing directories service 0x Reading the TCN messenger status 0x Writing the TCN messenger control 0x Registration of caller and replier functions 0x Cancel previous registration of caller and replier functions 0x Reading states of MD instances 0x Writing control of the caller instance 0x Writing control of the replier instance 0x Reading the station identifier service This service provides information about the station identifier of device itself. U16 Frame length (8 bytes) Service Ch8 Reading the station identifier service (0x80) U16 Frame length (10 bytes) Service Ch8 Reading the station identifier service (0x80) Status U8 Return code of processing state Station identifier U8 8-bit station identifier (255 = identifier not set) Reserved U8 Reserved Writing the station identifier service This service provides setting of station identifier of the device itself. U16 Frame length (10 bytes) 37/71 tcn-mvb-acp_ms_en_118

38 Service Ch8 Writing the station identifier service (0x81) Sequential U8 Session sequential number number Station identifier U8 8-bit station identifier Reserved U8 Reserved U16 Frame length (8 bytes) Service Ch8 Writing the station identifier service (0x81) Status U8 Return code of processing state Reading the routing directories service This service provides reading the content of routing directories (station, function and group directory). U16 Frame length (10 bytes) Service Ch8 Reading the routing directories service (0x82) Directory_ U8 of the directory: 1 station directory 2 function directory 3 group directory Reserved U8 Reserved Common response format is as follows: U16 Frame length (8 bytes) tcn-mvb-acp_ms_en_118 38/71

39 Service Ch8 Reading the routing directories service (0x82) Status U8 Return code of processing Entries number U32 Number of directory entries Directory... Depending on the type of the directory Station directory response format is as follows: U16 Frame length (10 + nr_entries * bytes) Service Ch8 Reading the routing directories service (0x82) Status U8 Return code of processing Entries number U32 Number of directory entries Station directory entry No. 1 Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Station directory entry No. 2 Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Station directory entry No. n Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Function directory response format is as follows: U16 Frame length (10 + nr_entries * bytes) Service Ch8 Reading the routing directories service (0x82) Status U8 Return code of processing Entries number U32 Number of directory entries 39/71 tcn-mvb-acp_ms_en_118

40 Function directory entry No. 1 Function id U8 Identification of the function Station id U8 Identification of the station which provides the function Function directory entry No. 2 Function id U8 Identification of the function Station id U8 Identification of the station which provides the function Function directory entry No. n Function id U8 Identification of the function Station id U8 Identification of the station which provides the function Group directory response format is as follows: U16 Frame length (10 + nr_entries + 2 bytes) Service Ch8 Reading the routing directories service (0x82) Status U8 Return code of processing Entries number U32 Number of directory entries Group 1 U8 Identification of the 1st group Group 2 U8 Identification of the 2nd group Group n U8 Identification of the group No. n Writing the routing directories service This service provides writing of entries into the routing directories (station, function and group directory). The maximum number of entries is 62 for the station directory, 249 for the function directory and 64 for the group directory. Common request format is as follows: U16 Frame length (min. 10 bytes) Service Ch8 Writing the routing directories service (0x83) Directory_ U8 of the directory: 1 station directory 2 function directory 3 group directory Reserved U8 Reserved tcn-mvb-acp_ms_en_118 40/71

41 Number of entries U16 Number of directory entries Directory... Depending on the type of the directory Writing station directory request format is as follows: U16 Frame length (10 + nr_entries * bytes) Service Ch8 Writing the routing directories service (0x83) Directory_ U8 1 station directory Reserved U8 Reserved Number of entries U16 Number of station directory entries Station directory entry No. 1 Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Station directory entry No. 2 Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Station directory entry No. n Reserved U8 Reserved Final station id U8 Identification of the final station Next station id U8 Identification of the next (router) station Bus identification U8 Identification of the bus Device address U32 Device address Writing function directory request format is as follows: U16 Frame length (10 + nr_entries * bytes) Service Ch8 Writing the routing directories service (0x83) Directory_ U8 2 function directory Reserved U8 Reserved 41/71 tcn-mvb-acp_ms_en_118