client modified by Daniel J. Lauk

Daniel J. Lauk — Thu, 10 Jul 2014 13:57:44 -0000

--- v1
+++ v2
@@ -1,25 +1,38 @@
 # Client Library

-NuGet package (binary only):
+The EpicsSharp project provides a C# implementation of the channel access protocol. This is the client part of the communication.
+
+## How to obtain
+
+The client library is available in the following ways:
+
+* **NuGet** package (binary only):
 https://www.nuget.org/packages/EpicsClient2/
-
-Download the client library here (client directory):
+* **Source** code: Download the client library here (client directory):
 https://sourceforge.net/p/epicssharp/code/

-Add the reference of the EpicsClient2 assembly to your project.
+In Visual Studio, add the reference of the `EpicsClient2` assembly to your project.

-To use it:
+
+## How to use
+
+We try very hard to keep the client facing API simple. We sincerely hope you appreciate that effort and the brevity of the examples. (Really, that *is* all the code you need.)
+
+
+### Reading a PV
+
+This example will read the EPICS PV `MY-EPICS-CHANNEL:VALUE`, requesting it as a `string`, and print out the received value on the console. Please note, that for the client program, the call to `channel.Get()` is *synchronous* (i.e. blocking).

 ~~~~~~
 EpicsClient client = new EpicsClient();
-client.Configuration.SearchAddress = "255.255.255.255:5064";
 var channel = client.CreateChannel<string>("MY-EPICS-CHANNEL:VALUE");
 Console.WriteLine(channel.Get());
 ~~~~~~

-the client.Configuration.SearchAddress can be left out and it will then use the default EPICS search port on the local broadcast address. You can however specify one or more search addresses separated by semi-colons.

-To use monitors instead of get use the event MonitorChanged:
+### Monitoring a PV
+
+To use EPICS monitors (called *events* in channel access) use the event `MonitorChanged`:

 ~~~~~~
 class Program
@@ -29,9 +42,8 @@
     static void Main(string[] args)
     {
         EpicsClient client = new EpicsClient();
-        client.Configuration.SearchAddress = "129.129.130.87:5432";

-        channel = client.CreateChannel<string>("ADG1:IST1:2");
+        channel = client.CreateChannel<string>("MY-EPICS-CHANNEL:VALUE");
         channel.StatusChanged += new EpicsStatusDelegate(channel_StatusChanged);
         channel.MonitorChanged += new EpicsDelegate<string>(channel_MonitorChanged);

@@ -50,4 +62,49 @@
 }
 ~~~~~~

-type += and then 2 tabs which will generate for you the skeleton callback function.
+**Tip:** In Visual Studio, type `+=` followed by 2 tabs. This will generate the skeleton callback function for you.
+
+
+### Using a gateway
+
+If your client needs to be on a different network than your server(s), e.g. if your office and machine networks are separated by firewalls, the EPICS default behaviour (a broadcast on the local network) will not work. You will have to use a channel access gateway. (Isn't it handy, the EpicsSharp project provides such a [gateway]?)
+
+With our client library, using a gateway is easy. In fact, it is even possible (and not really any harder) use multiple gateways, in case you need to communicate with several networks.
+
+
+#### Alternative 1: Specify the gateway in the code
+
+For quick tests you can provide the gateway(s) in the code like this:
+
+~~~~~~
+EpicsClient client = new EpicsClient();
+client.Configuration.SearchAddress = "192.168.1.50";
+~~~~~~
+
+**Please note** that you have to specify the gateway, **before** you create a channel.
+
+
+#### Alternative 2: Specify the gateway in the application configuration
+
+You can also specify the gateway(s) to use via the .NET configuration mechanism, i.e. in you `App.config` or `web.config` XML files. Just add the key `e#ServerList` to your `appSettings` like this, and the client library will pick it up:
+
+~~~~~~
+<appSettings>
+  <add key="e#ServerList" value="192.168.1.50"/>
+</appSettings>
+~~~~~~
+
+Using this approach has the following advantages, that if the address(es) of the gateways change, you do not need to rebuild your software and redistribute it.
+
+
+#### Gateway specification syntax
+
+The gateway to be used can be specified in the following ways (you're probably familiar with these already):
+
+* An IPv4 address in dotted notation, including a port number (e.g. `192.168.1.50:1234`)
+* An IPv4 address in dotted notation (e.g. `192.168.1.50`).
+  The EPICS default port will be used, which is 5064.
+* A host name, including a port number (e.g. `mygateway.example.org:1234`).
+* A host name (e.g. `mygateway.example.org`).
+  The EPICS default port will be used, which is 5064.
+* If you need to specify multiple gateways, separate the entries by semicolon (e.g. `gw1.example.org:1234;gw2.example.org:9876;192.168.1.50`).

client modified by Daniel J. Lauk

Daniel J. Lauk — Thu, 10 Jul 2014 12:50:46 -0000

Client Library

NuGet package (binary only):
https://www.nuget.org/packages/EpicsClient2/

Download the client library here (client directory):
https://sourceforge.net/p/epicssharp/code/

Add the reference of the EpicsClient2 assembly to your project.

To use it:

EpicsClient client = new EpicsClient();
client.Configuration.SearchAddress = "255.255.255.255:5064";
var channel = client.CreateChannel<string>("MY-EPICS-CHANNEL:VALUE");
Console.WriteLine(channel.Get());

the client.Configuration.SearchAddress can be left out and it will then use the default EPICS search port on the local broadcast address. You can however specify one or more search addresses separated by semi-colons.

To use monitors instead of get use the event MonitorChanged:

class Program
{
    static EpicsChannel<string> channel;

    static void Main(string[] args)
    {
        EpicsClient client = new EpicsClient();
        client.Configuration.SearchAddress = "129.129.130.87:5432";

        channel = client.CreateChannel<string>("ADG1:IST1:2");
        channel.StatusChanged += new EpicsStatusDelegate(channel_StatusChanged);
        channel.MonitorChanged += new EpicsDelegate<string>(channel_MonitorChanged);

        Console.ReadKey();
    }

    static void channel_MonitorChanged(EpicsChannel<string> sender, string newValue)
    {
        Console.WriteLine("Value: " + newValue);
    }

    static void channel_StatusChanged(EpicsChannel sender, ChannelStatus newStatus)
    {
        Console.WriteLine("Status: " + newStatus.ToString());
    }
}

type += and then 2 tabs which will generate for you the skeleton callback function.

Recent changes to client

client modified by Daniel J. Lauk

client modified by Daniel J. Lauk

Client Library