mirror of https://github.com/m-labs/artiq.git
106 lines
4.0 KiB
ReStructuredText
106 lines
4.0 KiB
ReStructuredText
Writing a driver
|
|
================
|
|
|
|
These instructions cover writing a simple driver for a "slow" device, that uses the controller mechanism.
|
|
|
|
The controller
|
|
--------------
|
|
|
|
A controller is a piece of software that receives commands from a client over the network (or the ``localhost`` interface), drives a device, and returns information about the device to the client. The mechanism used is remote procedure calls (RPCs) using :class:`artiq.management.pc_rpc`, which makes the network layers transparent for the driver's user.
|
|
|
|
The controller we will develop is for a "device" that is very easy to work with: the console from which the controller is run. The operation that the driver will implement is writing a message to that console.
|
|
|
|
For using RPC, the functions that a driver provides must be the methods of a single object. We will thus define a class that provides our message-printing method: ::
|
|
|
|
class Hello:
|
|
def message(self, msg):
|
|
print("message: " + msg)
|
|
|
|
To turn it into a server, we use :class:`artiq.management.pc_rpc`. Import the function we will use: ::
|
|
|
|
from artiq.management.pc_rpc import simple_server_loop
|
|
|
|
and add a ``main`` function that is run when the program is executed: ::
|
|
|
|
def main():
|
|
simple_server_loop(Hello(), "hello", "::1", 7777)
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
|
|
The parameters ``::1`` and 7777 are respectively the address to bind the server to (IPv6 localhost) and the TCP port to use. Then add a line: ::
|
|
|
|
#!/usr/bin/env python3
|
|
|
|
at the beginning of the file, save it to ``hello-controller`` and set its execution permissions: ::
|
|
|
|
$ chmod 755 hello-controller
|
|
|
|
Run it as: ::
|
|
|
|
$ ./hello-controller
|
|
|
|
and verify that you can connect to the TCP port: ::
|
|
|
|
$ telnet ::1 7777
|
|
Trying ::1...
|
|
Connected to ::1.
|
|
Escape character is '^]'.
|
|
|
|
:tip: Use the key combination Ctrl-AltGr-9 to get the ``telnet>`` prompt, and enter ``close`` to quit Telnet. Quit the controller with Ctrl-C.
|
|
|
|
Also verify that you can get the type of the server (the "hello" string passed to ``simple_server_loop``) using the ``identify-controller`` program from the ARTIQ front-end tools: ::
|
|
|
|
./identify-controller ::1 7777
|
|
Type: hello
|
|
|
|
The client
|
|
----------
|
|
|
|
Controller clients are small command-line utilities that expose certain functionalities of the drivers. They are optional, and not used very often - typically for debugging and testing.
|
|
|
|
Create a ``hello-client`` file with the following contents: ::
|
|
|
|
#!/usr/bin/env python3
|
|
|
|
from artiq.management.pc_rpc import Client
|
|
|
|
|
|
def main():
|
|
remote = Client("::1", 7777, "hello")
|
|
try:
|
|
remote.message("Hello World!")
|
|
finally:
|
|
remote.close_rpc()
|
|
|
|
if __name__ == "__main__":
|
|
main()
|
|
|
|
Run it as before, while the controller is running. You should see the message appearing on the controller's terminal: ::
|
|
|
|
$ ./hello-controller
|
|
message: Hello World!
|
|
|
|
When using the driver in an experiment, for simple cases the ``Client`` instance can be returned by the :class:`artiq.language.core.AutoContext` mechanism and used normally as a device.
|
|
|
|
Command-line arguments
|
|
----------------------
|
|
|
|
Use the Python ``argparse`` module to make the bind address and port configurable on the controller, and the server address, port and message configurable on the client.
|
|
|
|
We suggest naming the controller parameters ``--bind`` and ``--port`` so that those parameters stay consistent across controller, and use ``-s/--server`` and ``--port`` on the client.
|
|
|
|
The controller's code would contain something similar to this: ::
|
|
|
|
def _get_args():
|
|
parser = argparse.ArgumentParser(description="Hello world controller")
|
|
parser.add_argument("--bind", default="::1",
|
|
help="hostname or IP address to bind to")
|
|
parser.add_argument("--port", default=7777, type=int,
|
|
help="TCP port to listen to")
|
|
return parser.parse_args()
|
|
|
|
def main():
|
|
args = _get_args()
|
|
simple_server_loop(Hello(), args.bind, args.port)
|