Huntsman Telescope dome control

Code to run the Huntsman Telescope dome control hardware

Overview

The Huntsman Telescope dome control software has two components, one written in C++ the other in python.

The C++ component is a X2Dome driver that interfaces with TheSkyX and passes commands through to the python component. This is done using the gRPC framework, allowing the C++ component to pass information to the python component.

The python component is implemented on a raspberry pi that controls the dome rotation motor. It controls the activation of the motor and tracks the dome position using an encoder. It returns information (such as dome position) to the C++ component using gRPC as well.

The C++ code is built around Software Bisque's X2 standard. For more infomation on this see here <https://www.bisque.com/x2standard/class_x2_dome.html#a7ffd792950cdd0abe1b022e7a8caff9e>.

HOW TO RUN THE STUPID THING

For installation of dependencies/instructions for compiling and installing the required TheSkyX driver see sections below. Assuming everything is set up correctly, this is how you would set up the dome control system.

• Navigate to the directory containing the gRPC python server file
• $ cd huntsman-dome/domehunter/gRPC-server/
• Use the -h flag to get information on the available command line flags
• $ python huntsman_dome_server.py -h
• To run server in simulated hardware mode run with the -s flag
• $ python huntsman_dome_server.py -s
• Now the server is running, you may start TheSkyX
• Within TheSkyX go to the Dome Setup menu and select the Huntsman Telescope
• Open TheSkyX log window and place by the python server window to watch for activity/status messages

C++/gRPC Component

Built artefacts (libHuntsmanDome.so / .dylib and *.o) are not committed. Build the driver from source on the machine that runs TheSkyX, as below. The generated gRPC stubs (src/hx2dome.pb.*, src/hx2dome.grpc.pb.* and gRPC-server/hx2dome_pb2*.py) are committed. Regenerate them only after changing hx2dome.proto.

Requirements

Linux (Ubuntu/Debian): the distro gRPC and protobuf packages are enough. Tested on Ubuntu 24.04 with protobuf 3.21.12 and gRPC 1.51.1:

$ sudo apt install build-essential pkg-config \
      libgrpc++-dev libprotobuf-dev protobuf-compiler protobuf-compiler-grpc

MacOS (homebrew):

$ xcode-select --install
$ brew install grpc protobuf

If a packaged gRPC is not available, build it from source following gRPC's BUILDING.md.

Python (Raspberry Pi server side): install the package, which pulls in grpcio and grpcio-tools:

$ python -m pip install -e .          # add .[rpi] on the Pi for GPIO libs

Building the TheSkyX driver

Everything for the driver lives in domehunter/gRPC-TheSkyX-driver/:

• hx2dome.proto: the RPC definitions shared by the C++ and Python sides
• src/: the driver source plus the generated gRPC stubs
• Makefile_[LINUX,MAC]: build recipes
• TheSkyX_[LINUX,MAC]_plugin_install.sh and domelist HuntsmanDome.txt: install the built plugin into TheSkyX

1. Set the server address. The driver connects to the Python gRPC server at an address hard-coded in src/main.cpp (grpc::CreateChannel("<host>:50051", ...)). Edit it to point at the Raspberry Pi, or at localhost:50051 for local testing, before building.

2. (Only if hx2dome.proto changed) regenerate the stubs. Regenerate both sides so they stay in sync:

$ domehunter/gRPC-TheSkyX-driver/generate_grpc_cpp_code.sh
$ domehunter/gRPC-server/generate_grpc_python_code.sh

The C++ stubs must be generated by the same protobuf/gRPC version that the driver is linked against. The committed stubs came from protoc 3.21.12 and grpc_cpp_plugin 1.51.1 (Ubuntu 24.04). With a different toolchain, rerun the script before building, otherwise you get PROTOBUF_VERSION compile errors.

3. Build:

$ cd domehunter/gRPC-TheSkyX-driver/
$ make -f Makefile_LINUX              # or Makefile_MAC

This produces libHuntsmanDome.so (Linux) or libHuntsmanDome.dylib (Mac) in that directory. make -f Makefile_LINUX clean removes the library and object files. Always clean before rebuilding after regenerating stubs.

4. Install into TheSkyX (quit TheSkyX first):

$ ./TheSkyX_LINUX_plugin_install.sh   # or TheSkyX_MAC_plugin_install.sh

This copies the library into TheSkyX's PlugIns[64]/DomePlugIns/ and domelist HuntsmanDome.txt into Miscellaneous Files/. Restart TheSkyX and pick the Huntsman dome in the Dome Setup menu.

Running the servers

Start the dome gRPC server before issuing commands from TheSkyX:

$ cd domehunter/gRPC-server/
$ python huntsman_dome_server.py -h   # list options
$ python huntsman_dome_server.py -s   # simulated hardware
$ python huntsman_dome_server.py -d   # dummy replies, tests driver<->server link only
$ python huntsman_dome_server.py -r   # real hardware

The Musca shutter controller has its own gRPC server, which listens on port 50052 and is configured by gRPC-server/shutter_config.yml:

$ python domehunter/shutter_server.py [-c CONFIG] [-p PORT]

The human-written files are src/main.cpp/main.h (the X2 plugin entry point), src/x2dome.cpp/x2dome.h (forwards TheSkyX calls over gRPC), hx2dome.proto, and gRPC-server/huntsman_dome_server.py. Everything matching *.pb.* or *_pb2*.py is generated. Do not edit it by hand.

Python RaspberryPi Component

Requirements

Required:

• gpiozero python library

Optional:

• smbus and sn3218 python libraries

Note:

The smbus and sn3218 are used to control the automationHAT status LEDs. If you plan on running the code without the automationHAT these libraries aren't required.

Getting Started

Follow the example jupyter notebook in the examples direction (dome_control_example). The automationHAT hardware is not required to run the code in testing mode.

Tests

In order to run the test suite, go to the source direction (huntsman-dome/) and run the following command:

$ python -m pip install -e .[test]
$ python -m pytest domehunter

License

This project is Copyright (c) Huntsman Team and licensed under the terms of the BSD 3-Clause license. This package is based upon the Astropy package template which is licensed under the BSD 3-clause licence. See the licenses folder for more information.