Manual LNI 080822 - LONIX · LNI - Lonix Network Interface Manual . 2 (9) ... Additionally, the client can command LNI to poll or update any network variable in the LON-network. 5

1 (9)

LONIX OY Teollisuuskatu 33 Tel. +358 9 349 9853 VAT 1043054-9 www.lonix.com FIN-00510 Helsinki, Finland Fax +358 9 349 9863 Trade Reg.No. 678.356

LNI - Lonix Network Interface

Manual

2 (9)


Table of Contents 1. General ......................................................................................................................................... 3

1.1 Technical Data.......................................................................................................................... 3 1.2 Dimensions and Materials.......................................................................................................... 3

2. Initialization Procedures .................................................................................................................. 3 3. Establishing the Connection ............................................................................................................ 5 4. Usage............................................................................................................................................ 5 5. LNI TCP/IP -protocol Specification ................................................................................................... 5

5.1 LNI Initiated Messages .............................................................................................................. 6 5.2 Message Contents by Type ....................................................................................................... 7 5.3 Opening the Socket Connection................................................................................................. 9

3 (9)


1. General LNI-module is used as a gateway between the building automation network (LON-network) and IP-network (Ethernet). With LNI it’s possible to remotely monitor and control the appliances of the building automation system. LNI also works as a standard interface between COBA-server and automation network. LNI consists of Neuron-processor for LON-communication, a Rabbit-processor for IP-communication, the connectors for the busses and an RS-232-port for configuration. LNI works as an IP -server to which an IP-client can make a socket-connection.

1.1 Technical Data

HW-versions: 1.21 and 1.22 Supply Voltage: 12-24V DC/AC (50Hz) Power Consumption: 2W External Temperature: 10-50 °C / 20.. 95 Rh % Overload Protection: Recovery fuse 500mA: LON–transceiver: HW-version 1.1: FTT-10 HW-version 1.2: TP-1250 Processor: Neuron 3120 Clock Frequency: 10MHz IP-class: IP55 Installation Method: Service Pin Serial port parameters: 4800bps/8-N-1, no flow control

1.2 Dimensions and Materials

Enclosure: Hammond Dimensions: 120 mm * 78 mm * 46 mm Material: Aluminum Color: Metal gray Connector: Detachable 4-pole strip for wire 2.5 mm² max, 9-pole D-sub male RS-232, Ethernet RJ-45 Installation: on table, on the wall or 35mm DIN - rail Weight: 0.5 kg

2. Initialization Procedures The initialization of the LNI is done by configuring it via RS-232 port (4800bps/8-N-1, no flow control) with e.g. HyperTerminal running in PC. The LON-installation can be made with any LON-installation and maintenance software, e.g. LonMake or NL220. The initialization includes the configuration of own IP-address, subnet mask and port used, as well as the IP-address of the client and the password to establish a valid connection. The LON-installation for LNI is done like for any LON-based node, a service button is used to send the NeuronID over the network. LNI has some input network variables to which installer can bind outputs of other

4 (9)


nodes, typically alarm-outputs and other urgent messages are bound. The rest of the variables don’t need any bindings, since LNI is able to poll and update any network variable in the network (in the same domain). Having done all configurations, LNI is reset by cycling power, after which the configurations become effective. To start the initialization, type “get config all” <ENTER> and LNI should respond as follows:

To set the IP-address of LNI type: SET CONFIG IP XXX.XXX.XXX.XXX To set the network mask type: SET CONFIG NETMASK XXX.XXX.XXX.XXX To set the port to open type: SET CONFIG PORT XXXX To set the IP-address of the remote client type: SET CONFIG REMIP XXX.XXX.XXX.XXX The last line 123456 is the current IP-password of LNI. This is used when the client starts a new socket session with LNI. The session always starts with an authentication with the password. To set the IP-password type: SET CONFIG PW zzzzzz The LON-address of LNI may also be set via RS -port, then LNI is not ‘officially’ part of the LON installation. To make LNI able to communicate with the rest of the network, it must have the same domain address. To set the LON address of LNI type: SET CONFIG LONADDR dom-len domain subnet node.

NOTE! The parameters dom-len domain subnet and node all must be entered with hexadecimal values. NOTE! LNI THAT IS SELF-INSTALLED VIA RS-PORT DOES NOT SUPPORT ANY BOUND NETVARS, IT CAN HOWEVER UPDATE AND FETCH ANY NETVAR IN ANY NODE IN THE SAME DOMAIN. SO, NO REAL-TIME ALARM UPDATES ARE RECEIVED BY LNI, BUT THEY CAN BE POLLED PERIODICALLY. It is highly recommended to use node address above 120 to prevent duplicate-node situation. The subnet address should be selected correctly to ensure proper operation of the LON routers. So, use this feature with care!

5 (9)


3. Establishing the Connection After reset, LNI opens the configured port to listen a message from the client. If the transmit is not received before timeout, LNI closes the port and waits a few seconds before re-trying. The first message must be an authentication command containing a valid password. If the first message is of wrong type or the password is not correct, then LNI will close the port and the establishing procedure starts over. If the first message is correct, then the socket-connection is established and it will be kept on. If the connection is later lost, then the above described procedure is carried out.

4. Usage LNI is typically used to poll and update network variables by the BMS monitor. Since the view in the monitor is changed constantly by users, also the list of the desired network variables is changed. To be able to respond quickly, LNI maintains a list of the active variables to be polled. This list can be built and modified dynamically; normally COBA-server keeps track of this list. LNI polls the variables on the list, one after another, and if the polled value is different to the previous value, it’s forwarded to the client. If however, the value has not changed, it will not be forwarded. The maximum number of variables simultaneously on the list is 500. LNI removes the list, if the connection is lost between LNI and the client. Additionally, the client can command LNI to poll or update any network variable in the LON-network.

5. LNI TCP/IP-protocol Specification

TYPE ID RETCODE PARAM1 PARAM2 PARAM3 JNE DATA1 DATA2 etc

The number of parameters and data bytes is depends on the message types which are described in detail later. Following is a description of each field, its purpose and allowed values TYPE: One byte (8 bits) defines the message type. Available message type numbers are listed below:

GET_NV =1, SET_NV =2, GET_NV_FORMATTED =3, SET_NV_FORMATTED =4, GET_STATUS =5, STATUS_UPDATE =6, ADD_LISTENER =7, ADD_LISTENER_FORMATTED =8, REMOVE_LISTENER =9, CLEAR_LISTENER_TABLE =10, AUTHENTICATION_CMD =11, GET_NV_REPLY =101, SET_NV_REPLY =102, GET_NV_FORMATTED_REPLY =103, SET_NV_FORMATTED_REPLY =104, GET_STATUS_REPLY =105, STATUS_UPDATE_REPLY =106, ADD_LISTENER_REPLY =107, ADD_LISTENER_FORMATTED_REPLY=108,

6 (9)


REMOVE_LISTENER_REPLY =109, CLEAR_LISTE NER_TABLE_REPLY =110, AUTHENTICATION_CMD_REPLY =111, NV_UPDATE =201, NV_UPDATE_FORMATTED =202, ALARM_UPDATE =203,

The message types 1..11 are initiated by the client application to request LNI to perform some specific action. The message types 101..111 are the responses that LNI send back to the client as LNI has completed the requested action. NOTE! AT THE MOMENT (02/2008) FOLLOWING CLIENT MSG-TYPES ARE NOT SUPPORTED IN LNI APPLICATION: GET_NV_FORMATTED (3), SET_NV_FORMATTED (4), GET_STATUS (5), STATUS_UPDATE (6) ID: Two-byte identification number, set by the client and repeated by LNI in the respond message. The purpose is to work as a handle for message processing and re-directing in client. Allowed values 1-65535. Value 0 is reserved for LNI initiated messages which do not refer any previous message and will not be responded.

RETCODE: One byte return code to indicate success or failure in processing the action requested. RETCODE -enumerations: typedef enum { RETCODE_INIT =255, SUCCESS =0, FAIL =1, TIMEOUT =2, VALUE_INVALID =3, NOT_ALLOWED =4, NV_INVALID =5, LISTENER_TABLE_FULL =6, UNKNOWN_LISTENER_ENTRY =7, NV_LIST_OVERFLOW =8, } LNI_RETCODES; The client sets RETCODE to a value RETCODE_INIT, ie 255. A retcode value FAIL, i.e. 1 indicates an un-specified error, all the other retcodes specify the nature of error.

5.1 LNI Initiated Messages

Messages initiated by LNI, namely NV_UPDATE, NV_UPDATE_FORMATTED and ALARM_UPDATE are processed in a different way than the typical client initiated messages. LNI generates these messages spontaneously after having received an updated value to a network variable in the listener list or an alarm message into alarm input. These messages are not responded by the client. The ID field is always 0 and the RETCODE is always 0 (SUCCESS).

7 (9)


5.2 Message Contents by Type

Message types and parameters supported by LNI-version 1.00

NOTE: The DOMAIN-value must always be 0, this value refers to domain-table-index, and since LNI can be a member of only one domain, the index is 0. The actual domain address must be set be either LonWorks installation program or manually via RS -232-port with a terminal program.

GET_NV + GET_NV_REPLY SET_NV + SET_NV_REPLY ADD_LISTENER + ADD_LISTENER_REPLY REMOVE_LISTENER + REMOVE_LISTENER_REPLY CLEAR_LISTENER_TABLE + CLEAR_LISTENER_TABLE_REPLY AUTHENTICATION_CMD + AUTHENTICATION_CMD_REPLY NV_UPDATE ALARM_UPDATE

GET_NV:

1 ID 255 DOMAIN SUBNET NODE NV-INDEX

Purpose: to get the value of a network variable (netvar) in a specific node in the network.

GET_NV_REPLY:

101 ID RETCODE DOMAIN SUBNET NODE NV-INDEX DATALEN DATA0..30

Purpose: the respond to GET_NV message If RETCODE = 0 (SUCCESS) the field named DATALEN is included and the number of data bytes indicated by DATALEN. If RETCODE is not 0, there is no data. Other possible RETCODE-values are 2 (TIMEOUT), 8 (NV_LIST_OVERFLOW) ja 1 (FAIL). NV_LIST_OVERFLOW is received, if LNI is bombarded with GET_NV request faster than it can handle. LNI returns value FAIL, if the response received from the LON-network is not valid.

SET_NV:

2 ID 255 DOMAIN SUBNET NODE NV-INDEX DATALEN DATA0..30

Purpose: to set a value into a netvar in a specific node. SET_NV_REPLY:

102 ID RETCODE DOMAIN SUBNET NODE NV-INDEX

Purpose: the respond to SET_NV message Independently of the RETCODE value, only network address fields are included. Possible RETCODE values are the same as with GET_NV -message.

ADD_LISTENER:

7 ID 255 DOMAIN SUBNET NODE NV-INDEX Purpose: to add a listener point into LNI. LNI polls all the point in this list one after another in a round-robin fashion and sends the updated values to the client through TCP-socket

8 (9)


ADD_LISTENER_REPLY:

107 ID RETCODE DOMAIN SUBNET NODE NV-INDEX Purpose: the respond to ADD_LISTENER message RETCODE either 0 (SUCCESS) or 6 (LISTENER_TABLE_FULL)

REMOVE_LISTENER:

9 ID 255 DOMAIN SUBNET NODE NV-INDEX Purpose: to remove a point in the listener list

REMOVE_LISTENER_REPLY:

109 ID RETCODE DOMAIN SUBNET NODE NV-INDEX Purpose: the respond to REMOVE_LISTENER message Possible RETCODE values 0 (SUCCESS), 7 (UNKNOWN_LISTENER_ENTRY) or 1 (FAIL), if list is already empty.

CLEAR_LISTENER_TABLE:

10 ID 255

Purpose: to erase all point in listener list

CLEAR_LISTENER_TABLE_REPLY:

110 ID 0 (SUCCESS)

Purpose: the respond to CLEAR_LISTENER_TABLE message RETCODE always SUCCESS

AUTHENTICATION_CMD:

11 ID 255 LEN CH1 CH2 CH3 CH4 CH5 CH.. CH.. CH LEN

Purpose: to establish the socket connection between LNI and the client application. LNI can only be connected to one client. The IP -address of the client is defined via RS -232 by SET CONFIG REMIP command, see document LNI_description_ENG.doc for more details. CH1, CH2 etc are characters of the password AUTHENTICATION_CMD_REPLY:

111 ID RETCODE

Purpose: the respond to AUTHENTICATION_CMD message RETCODE = 0 (SUCCESS), or 1 (FAIL). If authentication fails, the socket connection is shut in 1 second by LNI.

NV_UPDATE:

201 0 0 DOMAIN SUBNET NODE NV-INDEX DATALEN DATA0..30

9 (9)


ID and RETCODE are always 0. LNI sends this message having received an updated value to a netvar in its listener list. If the value received is the same as previous value, no message is sent. Datalength 1..31 bytes, DATALEN indicates the length.

ALARM_UPDATE:

203 0 0 DOMAIN SUBNET NODE 0 60 DATA0..28 =

nviAlarm DATA29..60 = nviAlarmPos

ID and RETCODE are always 0. Domain/subnet/node-address refers the module that originally sent the alarm. Data0..60 contais the raw value received into nviAlarm and nviAlarmPos input netvars. NV_Index always 0. Datalength = 60.

5.3 Opening the Socket Connection

Client must start the session by sending AUTHENTICATION_CMD message with the correct password which is set to LNI via RS -232 port with command SET CONFIG PW xxxxxxx. The characters xxxxxx represent the password 1..31 characters in length. Allowed characters are all number and letters, upper or lower case. If the first message LNI receives is not an authentication message or the password is invalid, LNI shuts down the socket and tries to re-open it after 5 seconds. Then the authentication sequence can be re-tried. If the authentication sequence succeeds, LNI replies with AUTHENTICATION_CMD_REPLY message, and hereafter all the other commands are allowed. After successful authentication, LNI does not notify other authentication attempts. If the socket session is closed for some reason e.g. TCP network failure, LNI removes the whole listener list. So, after the re-connection the listener list must be re-build into LNI by the client.

Documents

Manual LNI 080822 - LONIX · LNI - Lonix Network Interface Manual . 2 (9) ... Additionally, the client can command LNI to poll or update any network variable in the LON-network. 5