| gclib 421 Communications API for Galil controllers and PLCs |

gcaps.md
1 # gcaps {#gcaps}
2
3 gcaps is a communication server natively supported by gclib to multiplex Galil
4 hardware communication features. It runs in the background on the host computer,
5 as a service or daemon.
6
7 Incidentally, the name *gcaps* is an acronym for the improbable name *Galil
8 Controller Asynchronous Proxy Server*. Yet another tidbit to impress friends at
9 parties.
10
11 ## gclib & gcaps
12 gclib will attempt to use gcaps whenever GOpen() is called without the
13 `--direct` or `-d` switch. Other than this small difference, gclib function calls
14 through gcaps operate as if the connetion was direct. The first version of gclib
15 supporting gcaps is 299.
16
17 At this time, gcaps must be running on the same host as gclib (localhost).
18 Contact Galil if connection to a remote host is desired.
19
20 ### Other gcaps Usage
21
22 The following functions will attempt to use gcaps first to gather data. If gcaps
23 is not found, the functions will fall back to user space calls to populate information.
24
25 |gclib Function | Usage | If gcaps unavailable |
26 |---------------|---------------------------------------------------------------------------------------|-----------------------------------------------|
27 | GVersion() | Provide the version of gclib and gcaps (if available). | No gcaps version. |
28 | GIpRequests() | Provide a list of all Galil controllers requesting IP addresses via BOOT-P or DHCP. | Must be root. |
29 | GAssign() | Assigns an IP address over the Ethernet to a controller at a given MAC address. | Must be root. |
30 | GAddresses() | Provides a listing of all available connection addresses. | Must be root, or user must be in device group.|
31
32 Because gcaps runs as a service on Windows, and as a system daemon on Linux, gcaps
33 runs with root privileges. See *If gcaps unavailable* column in the above table
34 when running without gcaps.
35
36 If gcaps is unavailable when these functions are run, a ~1 second delay will be
37 incurred while gclib searches for the absent server. In order to prevent gcaps
38 usage in these functions, comment out the symbol @ref G_USE_GCAPS in gclibo.h and
39 rebuild gclibo. See @ref gclibo.
40
41
42 ## gcaps Benefits
43
44 * Connections through gcaps multiplex a single connection resource. This means
45 that single-channel connection protocols like USB, RS232, or PCI can be shared with
46 as many simultaneous connections as needed. Furthermore, Ethernet-based
47 connections with gcaps leave plenty of Ethernet handles available for other
48 communications, such as MODBUS.
49 * All communications features are available to all connecting clients. This
50 means that a software application can be running simultaneosly with Galil's
51 diagnostic software (Galil Design Kit). This significantly simplifies support
52 and aides in debugging.
53 * Data Records, Messages, and Interrupts everywhere. No longer does one
54 connection *steal* data streams from another.
55 * gcaps runs as a service providing more capabilities than a user space application.
56 This allows functions like GIpRequests() and GAssign() to operate from a
57 gclib application without root privileges.
58
59 ## gcaps Installation
60 See the \link installation \endlink page to see if gcaps is available on your
61 OS. Support is marked with a diamond (&diams;).
62
63 If gcaps is needed on a different OS, please email softwaresupport@galil.com,
64 or call [Galil Applications](http://www.galil.com/contact).
65
66 ###Windows
67 gcaps is bundled in the gclib and GDK installer packages. Install with defaults
68 to get the gcaps service included. gcaps is also available as a standalone
69 installer. Downloads are available on the
70 <a href="http://www.galil.com/sw/pub/all/rn/gcaps.html">release notes</a> page.
71
72 gcaps is currently available only on **64 bit** Windows.
73
74 ###Linux
75 Instructions to install gcaps are listed with the instructions to install gclib.
76 Follow the link for your OS on the \link installation \endlink page.
77
78 gcaps is currently available only on **64 bit** versions of Linux.
79
80 ## Changes and updates to gcaps
81 See the <a href="http://www.galil.com/sw/pub/all/rn/gcaps.html">release notes</a> page.
82