====== Writing clients in Python ======

RTS2 provides three external bindings, which can be used by clients to interact with the RTS2 environment:

  - RTS2 protocol
  - XML/RPC protocol
  - JSON

JSON, standing for [[http://json.org|JavaScript Object Notation]], is probably the simplest to use. To demonstrate the simplicity of its use:

<code python>
# import library with RTS2 functions
import login
# for sleep function
import time
# sign on to JSON server
l = login.Login()
# this will pop out dialog box, asking user for credentials
l.signon()
# now set C0 temperature to -20
l.jsonProxy().setValue('C0','CCD_SET',-20)
temp = float(l.jsonProxy().getValue('C0','CCD_TEMP'))
while abs(float(temp + 20) > 0.5:
    print 'temperature',temp,'air temperature',l.jsonProxy().getValue('C0','CCD_AIR')
    # refresh cache..can be avoided by having timer running update, similar to loop which can be found in rts2ui
    l.jsonProxy().executeCommand('C0','info')
    l.refresh_cache()
    temp = float(l.jsonProxy().getValue('C0','CCD_TEMP'))
    # wait for 5 seconds
    time.sleep(5)
print 'Desired temperature reached',l.jsonProxy().getValue('C0','CCD_TEMP')
</code>

This code demonstrates how you can write a simple client in Python, which does things similar to C++ client provided in [[http://indilib.org/index.php?title=Developing_INDI_clients|the INDI tutorial]].
It illustrates the extreme simplicity of the external JSON API (in this case further masked by the Python library). After establishing connection, your client communicates via a kept-alive HTTP connection - so you don't pay the extra price for opening and closing communication.

JSON is much more dense then XML, so messages are shorter, and parameters are passed as URL parameters - you can talk to the server with a web-browser (or wget command), which is handy for debugging.

Errors are propagated as standard Python errors, and as they are not caught, they will ordinarily cause a client to terminate with a traceback writen to standard output. If you wish to catch possible errors, all you have to do is to add try-except blocks.

This also provides basic security, as a login is required.  To disable external access entirely, just kill rts2-xmlrpcd, which provides the service.