[Next] [Previous] [Top] [Contents] [Index]

Channel Access Client Reference

CHAPTER 1 Configuration

1.1 Why Reconfigure Channel Access

Typically an EPICS site will choose to reconfigure Channel Access because:

They wish for two or more independent projects to share the same network without fear of interaction between their control systems.
They wish to setup a test system that does not interact with an operational system.
They wish to setup a system that uses address lists instead of broadcasts for name resolution and server beacons.
They wish to setup a system that uses multiple IP subnets.
They wish to adjust client disconnect time outs or server beacon intervals.
They wish to use EPICS time stamps from a client that is in a time zone other than the US Mountain Time Zone.

1.2 EPICS Environment Variables

All channel access configuration occurs through EPICS environment variables. Table 1 on page 4 contains a list of all of the EPICS environment variables related to channel access.

TABLE 1. Channel Access EPICS Environment Variables
Environment Variable Name Range Default Section
EPICS_CA_ADDR_LIST <none> 1.3
EPICS_CA_AUTO_ADDR_LIST YES 1.3
EPICS_CA_CONN_TMO seconds 30.0 1.5
EPICS_CA_BEACON_PERIOD seconds 15.0 1.5
EPICS_CA_REPEATER_PORT 5065 1.4
EPICS_CA_SERVER_PORT 5064 1.4
EPICS_TS_MIN_WEST minutes 360 1.6

Environment Variable Name	Range	Default	Section
EPICS_CA_ADDR_LIST		<none>	1.3
EPICS_CA_AUTO_ADDR_LIST		YES	1.3
EPICS_CA_CONN_TMO	seconds	30.0	1.5
EPICS_CA_BEACON_PERIOD	seconds	15.0	1.5
EPICS_CA_REPEATER_PORT		5065	1.4
EPICS_CA_SERVER_PORT		5064	1.4
EPICS_TS_MIN_WEST	minutes	360	1.6

When executing under UNIX, EPICS environment variables can be modified by typing 'setenv <EPICS environment variable name> "<new value for the variable>"'. On IOCs, EPICS environment variables can be modified by adding a line of the form '<EPICS environment variable name> DBF_STRING <new value for the variable>' to the resource definition file (typically "resource.def" in the application directory that the IOC boots from). In the IOC start-up script the single argument to iocInit() should be the name (and potentially the file system path) of the resource definition file.

1.3 CA and Wide Area Networks

Normally in a local area network (LAN) environment CA discovers the address of the host for an EPICS channel by broadcasting frames containing a list of channel names (CA search messages) and waiting for responses from the servers that host the channels identified. Likewise CA clients efficiently discover that CA servers have recently joined the LAN or disconnected from the LAN by monitoring periodically broadcasted "beacons" sent out by the servers. Since hardware broadcasting requires special hardware capabilities, we are required to provide additional configuration information when EPICS is extended to operate over a wide area network (WAN).

1.3.1 IP Network Administration Background Information

EPICS Channel Access is implemented over the internet protocols (IP). IP addresses are divided into host and network portions. The boundary between each portion is determined by the IP "netmask". Portions of the IP address corresponding to zeros in the "netmask" specify the hosts address within an IP "subnet". Portions of the IP address corresponding to binary ones in the "netmask" specify the address of a host's IP "subnet". It is easy to examine these parameters on most UNIX hosts by typing "netstat -i". More detailed information can be obtained by typing "ifconfig <interface name>" where <interface name> was obtained from the output of "netstat". Similarly this information can be obtained from the vxWorks operating system by typing "ifShow".

Normally the scope of a broadcasted frame will be limited to an IP subnet however it is possible for a host on one IP subnet to issue a broadcast frame on a different IP subnet. Addresses with the host address portion set to all zeros or all ones are special. Modern IP implementations reserve destination addresses with the host portion set to all ones for the purpose of sending broadcasts to a particular subnet. Therefore in theory we can issue a broadcast frame on any broadcast capable LAN within the interconnected internet by specifying the proper subnet address combined with a host portion set to all ones. In practice this ability to send "directed broadcasts" may be limited by configuration options in routers which determine if these directed broadcasts are discarded.

The proper directed broadcast address required to reach a particular vxWorks host can be obtained by logging into that host and typing "ifShow". Ignore the loop back interface and use the broadcast address associated with the interface along the path to your router (usually there is only one choice here - ei). Similarly the proper broadcast address required to reach a particular UNIX host can be found by typing "netstat -i "followed by "ifconfig <interface name>" (usually "ifconfig leo").

IP ports are positive integers. Within the IP protocols the IP address, port number, and protocol type uniquely identify the source and destination of a particular frame on particular host computers. In practice the port number also uniquely identifies a protocol layered over one of the IP protocols. Servers are usually addressed by a "well known" port number. Clients are usually assigned a unique port number during initialization. IP ports below 1024 are reserved for servers that provide standardized facilities such as mail or file transfer. Port number between 1024 and 5000 are normally reserved for clients and other dynamic port number assignments.

1.3.1.1 Configuring vxWorks in a WAN environement

By default vxWorks hosts boot with default routes configured for the host's subnet. If a CA server is operating in a WAN environment it may be necessary to configure routes into the vxWorks system which enable the CA UDP server to respond to requests originating outside the hosts subnet.

routeShow()
hostAdd "the-router", "N.N.N.N"
routeAdd "0","the-router"

Note that some routers will be configured to not forward directed broadcasts. Note also that by not providing routes outside of a limited set of subnets an EPICS system manager can easily limit access to a particular host.

1.3.2 Configuring CA for Multiple Subnets

During initialization CA builds a list of the destination addresses used when sending CA client name resolution (search) requests and CA server beacons. This table is initialized by traversing the IP interfaces attached to the host. For each interface found that is attached to a broadcast capable IP subnet the broadcast address of that subnet is added to the list. For each point to point interface found the destination address of that link is added to the list. This available network interface driven initialization is skipped only if the EPICS environment variable "EPICS_CA_AUTO_ADDR_LIST" exists and its value is one of either "no" or "NO".

UNIX:
% setenv EPICS_CA_AUTO_ADDR_LIST YES

vxWorks:
Add the following line to the file "resource.def".
EPICS_CA_AUTO_ADDR_LIST DBF_STRING YES
% iocInit "resource.def"

Next the list of destination addresses is appended to by any IP addresses specified in the EPICS environment variable "EPICS_CA_ADDR_LIST". An identical procedure is followed by the server when it initializes the list of addresses that the server sends beacons to. Proper configuration of CA for multiple subnets requires that CA name resolution (search requests) frames pass from CA clients to the targeted CA servers. Likewise proper operation also requires that beacons issued by the targeted CA servers reach the hosts of all potential clients. For this reason the "EPICS_CA_ADDR_LIST" environment variable parameter will often be identical within a group of clients that communicate between themselves. The contents of EPICS_CA_ADDR_LIST is currently constrained to be a list of dot format IP addresses seperated by white space. Host names may not be substituted for IP addresses because some of the operating system environments in which CA runs do not support host name to IP address translation.

UNIX:
% setenv EPICS_CA_ADDR_LIST "1.2.3.255 8.9.10.255"

vxWorks:
Add the following line to the file "resource.def".
EPICS_CA_ADDR_LIST DBF_STRING 1.2.3.255 8.9.10.255
% iocInit "resource.def"

Note that there is no requirement that the addresses specified in the EPICS_CA_ADDR_LIST be a broadcast addresses. However this will often be the most convenient choice.

1.4 Configuring the IP port numbers utilized by CA

CA uses two TCP/IP port numbers and two UDP/IP port numbers as identified in Table 2 on page 7.

Channel Access Port Numbers
Protocol Default Purpose
TCP/IP 5064 Server
TCP/IP 5065 Reserved for future expansion
UDP/IP 5064 Process variable name resolution
UDP/IP 5065 Repeater (broadcast fan out within a host)

Channel Access Port Numbers
Protocol	Default	Purpose
TCP/IP	5064	Server
TCP/IP	5065	Reserved for future expansion
UDP/IP	5064	Process variable name resolution
UDP/IP	5065	Repeater (broadcast fan out within a host)

A particular site may choose to reconfigure the IP port numbers used by Channel Access. This will normally occur because a site wants to setup two or more completely independent control systems that will share all or part of the same network. For instance a site may wish to setup an operational control system and a test control system on the same network. The operational system might be assigned special port numbers and the test control system might be assigned the default CA port numbers. This configuration would allow the test system and the operational system to use identical PV names without fear of collision. A site may also need to configure the CA port numbers because some other facility at the site has already reserved the two default port number that are normally used by CA.

UNIX:
% setenv EPICS_CA_REPEATER_PORT 20000
% setenv EPICS_CA_SERVER_PORT 20001

vxWorks:
Add the following line to the file "resource.def".
EPICS_CA_REPEATER_PORT DBF_STRING 20000
EPICS_CA_SERVER_PORT DBF_STRING 20001
% iocInit "resource.def"

1.5 Configuring Disconnect Time Out / Server Beacon Period

If CA has not seen a beacon from a server that it is connected to for EPICS_CA_CONN_TMO seconds then an echo message is sent to the server over TCP/IP. If this echo message isn't replied to by the server within 5 additional seconds then the client will assume that the server is no longer present on the network and disconnect. Disconnecting implies notification of any application programs that may be using Channel Access to communicate with the server in question. Disconnecting also implies releasing any resources reserved while communicating with the missing server. The parameter EPICS_CA_CONN_TMO is specified in floating point seconds. Note that for short time outs, the delay until disconnect will also depend on the rate at witch applications poll into the CA client library (and allow CA background activity to be attended to).

UNIX:
% setenv EPICS_CA_CONN_TMO 15.0

vxWorks:
Add the following line to the file "resource.def".
EPICS_CA_CONN_TMO DBF_STRING 15.0
% iocInit "resource.def"

When a CA server initializes it initially sends "beacon" messages to each address specified in EPICS_CA_ADDR_LIST, and also any addresses auto configured from network interfaces found, with a very short period between "beacons". However, this short period is doubled each time a "beacon" is sent so that it will rapidly reached a plateau specified by EPICS_CA_BEACON_PERIOD. The parameter EPICS_CA_BEACON_PERIOD is specified in floating point seconds. For efficient operation it is recommended that EPICS_CA_BEACON_PERIOD be set to at least one half of the value specified for EPICS_CA_CONN_TMO.

UNIX:
% setenv EPICS_CA_BEACON_PERIOD 7.5

vxWorks:
Add the following line to the file "resource.def".
EPICS_CA_BEACON_PERIOD DBF_STRING 7.5
% iocInit "resource.def"

1.6 Configuring the Time Zone

While the CA client library does not translate in between the local time and raw EPICS time zone independent time stamps, many EPICS client side applications do call core EPICS libraries which provide this service. Therefore, users will need to configure the correct time zone prior to using EPICS client side application programs for the first time. To set the correct time zone users must compute the number of positive minutes west of GMT (maximum 720 inclusive) or the negative number of minutes east of GMT (minimum -720 inclusive) of the local time zone. This integer value is then placed in the variable EPICS_TS_MIN_WEST.

UNIX:
% setenv EPICS_TS_MIN_WEST 420

vxWorks:
Add the following line to the file "resource.def".
EPICS_TS_MIN_WEST DBF_STRING 420
% iocInit "resource.def"

Time Zone Examples
Time Zone EPICS_TS_MIN_WEST

USA Eastern 300

USA Central 360

USA Mountain 420

USA Pacific 480

Alaska 540

Hawaii 600

Japan -540

United Kingdom -60

Germany -120

Time Zone Examples
Time Zone	EPICS_TS_MIN_WEST
USA Eastern	300
USA Central	360
USA Mountain	420
USA Pacific	480
Alaska	540
Hawaii	600
Japan	-540
United Kingdom	-60
Germany	-120

1.7 Configuring a CA server

This chapter under construction.

Read this section only if you need to configure a CA server which must have a different configuration than then any clients which may be running in the same address space

exspecially

TABLE 4
Environment Variable Name Range Default Section
EPICS_CAS_ADDR_LIST <none> 1.7.1
EPICS_CAS_SERVER_PORT <none> 1.7.2
EPICS_CAS_BEACON_ADDR_LIST <none> 1.7.3
EPICS_CAS_BEACON_PORT <none> 1.7.4
CA Server EPICS Environment Variables

Environment Variable Name	Default	Section
EPICS_CAS_ADDR_LIST	<none>	1.7.1
EPICS_CAS_SERVER_PORT	<none>	1.7.2
EPICS_CAS_BEACON_ADDR_LIST	<none>	1.7.3
EPICS_CAS_BEACON_PORT	<none>	1.7.4

1.7.1 Configuring the Server's Address

1.7.2 rConfiguring the Server's Port

1.7.3 Configuring the Beacon Destination Address List

1.7.4 Configuring the Beacon Destination Port

The server must build a list of addresses to send beacons to. If EPICS_CA_AUTO_ADDR_LIST has the value "YES" then the beacon address list will contain at least the broadcast address of all LAN interfaces found in the host and the destination address of all point-to-point interfaces found in the host. If EPICS_CAS_BEACON_ADDR_LIST is defined then its contents will be used to augment this list. Otherwise, if EPICS_CA_ADDR_LIST is define its contents will be used to augment this list.

1.1 - Why Reconfigure Channel Access
1.2 - EPICS Environment Variables
1.3 - CA and Wide Area Networks
1.3.1 - IP Network Administration Background Information
1.3.1.1 - Configuring vxWorks in a WAN environement
1.3.2 - Configuring CA for Multiple Subnets
1.4 - Configuring the IP port numbers utilized by CA
1.5 - Configuring Disconnect Time Out / Server Beacon Period
1.6 - Configuring the Time Zone
1.7 - Configuring a CA server
1.7.1 - Configuring the Server's Address
1.7.2 - rConfiguring the Server's Port
1.7.3 - Configuring the Beacon Destination Address List
1.7.4 - Configuring the Beacon Destination Port

Channel Access Client Reference - 11 DEC 1996

[Next] [Previous] [Top] [Contents] [Index]