Metadata-Version: 2.4
Name: pyglobalcache
Version: 0.3.0
Summary: Simple Python API and command line program to access GlobalCaché hardware using its TCP socket interface.
Author-email: Bengt Martensson <mail@bengt-martensson.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bengtmartensson/pyglobalcache
Project-URL: Issues, https://github.com/bengtmartensson/pyglobalcache/issues
Keywords: globalcache,infrared-control
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pyglobalcache

Simple Python API and command line program to access GlobalCaché hardware using its TCP socket interface, described in the document [Global Caché Unified TCP API](https://www.globalcache.com/files/docs/api-gc-unifiedtcp.pdf). It somewhat resembles the program [Lirconian](https://github.com/bengtmartensson/Lirconian).

It supports most of the functionallity of the GlobalCaché products GC-100, iTach, iTach Flex and Global Connect. Not implemented are the reading of digital inputs, as well as the commands only present in the Global Connect. 

The source is maintained on [GitHub](https://github.com/bengtmartensson/pyglobalcache), and is licensed under the [Apache-2.0 license](https://www.apache.org/licenses/LICENSE-2.0). 

Feedback, bug reports, patches, etc, are welcome, preferrably as issues on GitHub,



(If you are looking for a GUI program to send IR signals to a GlobalCaché, look at [IrScrutinizer](https://github.com/bengtmartensson/IrScrutinizer/) instead.)

## Installation

This program/module is distributed through [PyPi](https://pypi.org/), and can thus be installed by the command `pip install pyglobalcache`, see [this guide](https://packaging.python.org/en/latest/tutorials/installing-packages/). The API library allows for calling the functionallity from your own Python by importing the module  `pyglobalcache`.

## Command line usage

The command line program is installed by PyPi, and is also called `pyglobalcache`.  It is a command with subcommands, described as 

```
usage: pyglobalcache [-h] [-i IP] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                   [--tcpport TCPPORT] [-p port] [-m MODULE] [-t TIMEOUT] [-I]
                   [-V] [-v]
                   command ...

Program to send IR codes, serial commands and relay commands to a GlobalCache.

positional arguments:
  command
    sendir              Send an IR signal.
    getinput            Get a digital input (not yet implemented).
    serial              Send a string to a serial port, get the response.
    relay               Set or clear a relay.
    version             Inquire version of the GlobalCache. (Use "--version"
                        for the version of this program.)
    getserial           Inquire current serial parameters.

options:
  -h, --help            show this help message and exit
  -i, --ip, -a, --address IP
                        IP address or name of GlobalCache
  -l, --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level
  --tcpport TCPPORT     TCP port of GlobalCache, default 4998
  -p, --port port       Port to use within selected module on GlobalCache,
                        default 1
  -m, --module MODULE   Module on GlobalCache, default 1
  -t, --timeout TIMEOUT
                        Timeout in seconds
  -I, --immediate_close
                        Close the GlobalCache immediately after every
                        interaction
  -V, --version         Display version information for this program
  -v, --verbose         Have the communication with the GlobalCache echoed
```

### Sending IR commands

IR commands are sent using the subcommand `sendir`:

```
usage: pyglobalcache sendir [-h] [-c COMMANDNAME] [-f FILENAME]
                            [--count COUNT]
                            [pronto_hex_numbers ...]

positional arguments:
  pronto_hex_numbers    Numbers making up a pronto hex ir signal, or "-" for
                        reading from stdin

options:
  -h, --help            show this help message and exit
  -c, --command COMMANDNAME
                        Named command to send from file in filename
  -f, --file FILENAME   File containing command definitions
  --count, -# COUNT     Number of times to send command
```

The command can be given either as [Pronto Hex](https://www.harctoolbox.org/Glossary.html#ProntoSemantics)  or as a command name, contained in a supplied text file. The Pronto Hex can be given either on the command line, or (by using "-" on the command line) read from standard input stdin. The text file should consist of the command line on  one line, then one (probably long) line containing the Pronto Hex line, then an empty line, repeated for all the commands. (This format is generated by [IrScrutinizer](https://github.com/bengtmartensson/IrScrutinizer/)'s export format ` Text`, selecting (only) the subformat ` Pronto Hex`.)

#### Examples

```
pyglobalcache -m 2 -p 1 sendir -f sonytv.txt -c ok -# 3
```

This sends three copies of the `ok`command, contained in the text file `sonytv.txt`to a Global Cache at the IP address 192.168.1.70 (the default), using port 1 of module 2. (Sony devices normally requires 3 copies of an IR command.)

```
irptransmogrifier render -p -n D=1,F=21 sony12 | pyglobalcache -m 2 -p 1 -i 192.168.1.70 sendir -# 3 -
```

(Requires IrpTransmogrifier to be installed. This is normally the case when [IrScrutinizer](https://github.com/bengtmartensson/IrScrutinizer/) is installed.) Generates an IR signal with the protocol Sony12, parameters D=1, F=21 (which toggles power on a Sony TV) in Pronto Hex format, send it through the pipe to the current program, which transmits it as IR send command to a GlobalCache with the given IP, module and port. 

### Sending/receiving serial commands

```
usage: pyglobalcache serial [-h] message

positional arguments:
  message     String to send to the serial port

options:
  -h, --help  show this help message and exit
```

This sends a message through a serial port, and receives the immediate response. (For more complex scenarios, the API can be used.)

#### Example

```
pyglobalcache -i gc2 -m 2 serial MV?
```

Sends the string `MV?`to the serial port on module 2 on a GlobalCaché, known to a local name server by the name of `gc2`, and displays the response. (Assuming a Denon AV Receiver/Amplifier, this returns the current master volume.) 

### Controlling relays

```
usage: pyglobalcache relay [-h] {on,off,toggle,pulse,?}

positional arguments:
  {on,off,toggle,pulse,?}
                        Value to set the relay to, ? to report current value

options:
  -h, --help            show this help message and exit
```
