Gimbal Software Interface

1. Introduction

Communication with the Galil motion controller is handled using gclib.py which provides the interface for sending commands and receiving responses from the controller. On top of this gimbal_lib.py was developed to simplify control using azimuth and elevation angles. This library manages motion commands position tracking coordinate conversion and safety limits to ensure the gimbal operates within its mechanical range.

Using this framework several application scripts were developed including satellite tracking scripts which was covered during the interim report, manual control using a WASD interface and automated Sun tracking for calibration and testing.

For more information on the satellite tracking scripts and how it is meant to be used, please use this link to access from the interim report website: https://wendahere.github.io/GS5/gimble/

2. Objective

The objective of the software subsystem is to develop control scripts that enable reliable operation of the gimbal system for testing and tracking applications. The software is designed to verify the accuracy of gimbal positioning and to evaluate the mechanical limits of the hardware through controlled motion.

It also supports troubleshooting by allowing direct control and observation of system behaviour during operation. In addition the software enables satellite tracking based on calculated position data and supports signal reception as part of the ground station functionality.

3. Software Architecture

Software architecture flow

The gimbal control software follows a layered architecture flow where different components are separated based on their function within the control system. This structure allows higher-level control scripts to operate independently from the low-level hardware communication layer.

At the top level, the application layer generates the desired azimuth and elevation commands based on user input or tracking algorithms. These commands are processed by gimbal_lib.py, which manages motion execution and translates the requested angles into controller-compatible commands.

The commands are then transmitted through gclib.py which provides the interface for communication with the Galil motion controller. The controller subsequently drives the azimuth and elevation motors to achieve the requested antenna orientation.

4. Gimbal Coordinate System

The gimbal operates using a two-axis coordinate system which consists of azimuth (AZ) and elevation (EL). These angles define the orientation of the antenna relative to the ground station reference frame (True North).

For the remounted gimbal configuration the azimuth axis is defined within a range of −90° to +90°. 0° corresponds to the true North direction and positive angles correspond to rotation toward the East and negative angles correspond to rotation toward the West.

The elevation axis is defined within a range of −90° to +90°. 0° represents the vertical upward direction. Positive elevation angles correspond to rotation toward the South horizon while negative angles correspond to rotation toward the North horizon.

These limits are enforced within the control software to prevent the gimbal from exceeding its mechanical motion range during manual operation or automated tracking.

5. Core software libraries

1. gclib.py:

• Provides the low-level communication interface between Python and the Galil motion controller
• Loads the appropriate controller drivers depending on the operating system
• Establishes and manages the controller connection using commands such as GOpen() and GClose()
• Sends motion commands to the controller using GCommand()
• Retrieves controller responses and error messages for monitoring and debugging

1. Gimbal_lib.py:

• Custom library developed to simplify control of the two-axis gimbal system
• Converts azimuth and elevation angles into encoder counts required by the Galil controller
• Initializes motion parameters such as speed, acceleration and deceleration
• Synchronizes gimbal position using encoder feedback from the controller
• Enforces azimuth and elevation motion limits to prevent mechanical over-rotation
• Provides high-level steering functions such as degSteer() for absolute or relative gimbal movement

6. Manual Control Mode [ WASD ]

6.1 Objective

The manual control mode using keyboard interface of “W,A,S,D” was developed to allow direct real-time control of the gimbal during hardware testing and debugging. Unlike the automated tracking scripts, this mode enables the operator to steer the antenna manually using keyboard inputs. This is useful for calibration, manual pointing, motion verification and checking the response of the azimuth and elevation axes before running higher-level tracking algorithms.

6.2 Control Inputs

The script uses W, A, S, D keys to jog the gimbal’s azimuth and elevation axes:

• A: rotate azimuth in anti-clockwise ( -ve AZ, towards the West )
• D: rotate azimuth in clockwise ( +ve AZ, towards the East )
• W: rotate elevation in anti-clockwise ( -ve EL )
• S: rotate elevation in clockwise ( +ve EL)
• SPACE: stop all motion using ramped deceleration
• ESC: terminate the script

The gimbal will continue in motion while the corresponding key is being held and stops when the key is released.

6.3 Overall Function of the Script

The manual_controlv3.py script provides a real-time interface for manually steering the gimbal using keyboard inputs. The program detects key presses through the pygame interface and translates them into motion commands for the azimuth (AZ) and elevation (EL) axes. Jog commands are sent to the Galil motion controller using the JG and BG commands while ST commands stop the motion.

Acceleration and deceleration ramps are implemented using the Galil AC and DC parameters to ensure smooth start and stop behaviour. The script also periodically reads the encoder position using the TP command and converts the returned counts into azimuth and elevation angles for live monitoring.

To verify the control logic before connecting to the physical gimbal hardware, a dry-run mode was implemented using the --dry-run argument. In this mode, motion commands are simulated instead of being transmitted to the Galil controller. The script prints the expected commands and updates the simulated azimuth and elevation positions while applying the same acceleration and deceleration logic. This allows the control flow, keyboard inputs, and motion behaviour to be checked safely before operating the actual system. Limits can also be set in the code itself to ensure that the gimbal will not exceed the rotational limits that are not being intended.

Dry-run execution of the manual WASD control script showing the terminal output and graphical interface used to monitor simulated azimuth and elevation motion.

6.4 External Libraries & Dependencies

1. argparse:
   - Used to parse command-line arguments such as controller address, jog speed, acceleration, deceleration, polling rate and dry-run mode. This allows the script behaviour to be adjusted without modifying the source code.

2. sys:
   - Used for safe program termination through sys.exit(main()).

3. time:
   - Used for timing operations such as controller polling intervals, print update intervals and simulation timing in dry-run mode.

4. pygame:
   - Used to create the keyboard-based control interface. It detects key presses in real time, manages the display window and updates the live position information shown to the operator.

5. gimbal_lib.GimbalController:
   - Provides the interface between the WASD script and the Galil motion controller. It supplies controller connection, encoder scaling factors, and low-level command access required for gimbal motion control.

6.5 Testing & Validation

Live Terminal OUTPUT

Live Tracking Test with code

The developed WASD-based control interface was tested to validate the functionality of the gimbal system and the results show that the gimbal responds accurately to user inputs with both azimuth and elevation axes moving as intended in real time. Software-defined angular limits were implemented to ensure that the gimbal operates within a safe range preventing excessive rotation and potential mechanical interference and these limits can be easily adjusted within the code to suit different operational requirements. In addition, acceleration and deceleration ramping were incorporated into the control logic resulting in smooth start and stop motions that reduce sudden jerks and minimize mechanical stress on the system. Overall, the testing confirms that the manual control system is reliable, responsive and capable of safely operating the gimbal under user input while also providing a stable foundation for further automated tracking implementation.

7. Sun Tracking Mode [ G/T Testing ]

7.1 Objective

The Sun tracking script was developed to automatically steer the antenna towards the Sun for calibration and system testing. In satellite ground stations, the Sun can be used as a stable astronomical reference source for antenna gain-to-noise temperature (G/T) measurements. By tracking the Sun’s position continuously, the antenna can be aligned with a known signal source to evaluate the performance of the RF chain and overall receiving system.

In addition, the Sun tracking mode provides a practical method for verifying the tracking algorithm, coordinate transformation, and motion control of the gimbal system before performing satellite tracking operations.

7.2 Overall Function of the Script

The sun_tracker.py script performs real-time Sun tracking by first obtaining the ground station location from the GPS module and then computing the Sun’s azimuth and elevation using the Skyfield astronomical library. These sky coordinates are converted into the remounted gimbal coordinate system before being sent to the motion controller through gimbal_lib.py.

To improve motion smoothness, the script uses PCHIP Hermite interpolation to generate intermediate target points between successive Sun position updates. This reduces abrupt changes in pointing commands and produces smoother antenna motion during tracking. A smart flip logic with hysteresis is also implemented to prevent unstable switching when the target approaches the azimuth boundary due to the gimbal’s +90 to -90 limitations as we are unable to access full 360 degrees in the Azimuth. As a result, we will be able to still have access to full 360 view even without the mechanical capability of the gimbal’s azimuth being unable to reach 360 degrees.

Before sending motion commands, the script applies an elevation cutoff and clamps the final gimbal angles within the allowed azimuth and elevation limits. The resulting pointing commands are then transmitted to the Galil controller through the degSteer() function in gimbal_lib.py.

A dry-run mode is also included to test the tracking algorithm without commanding the physical gimbal hardware. In this mode, the script prints the calculated sky coordinates, converted gimbal coordinates, and flip state to the terminal. This allows the coordinate conversion logic, interpolation behaviour, and safety constraints to be verified before live testing.

Dry-run execution of the sun-tracking control script showing the terminal output

The dry-run terminal output shows the calculated gimbal azimuth and elevation angles based on the tracked position of the Sun using the Skyfield library. This confirms that the control script is able to correctly compute the required pointing direction without commanding actual hardware movement. When the system is executed with dry_run set to false the gimbal will move according to these calculated angles in real time allowing it to continuously track the Sun’s position.

7.3 External Libraries & Dependencies

1. time:
   - Used for timing control and scheduling the tracking loop.

2. datetime:
   - Used for generating time offsets when sampling the Sun position over each update interval.

3. typing:
   - Used for type hints such as Tuple and List to improve code clarity and structure.

4. skyfield.api:
   - Used to load the astronomical ephemeris data and compute the Sun’s azimuth and elevation relative to the ground station.

5. gps_reader.read_once:
   - Used to retrieve the ground station latitude, longitude, altitude and heading source from the GPS module before tracking begins.

6. gimbal_lib.GimbalController:
   - Used to transmit the computed azimuth and elevation steering commands to the Galil motion controller.

7.4 Testing & Validation

Live Terminal Output

Gimbal Facing the sun’s location

The sun-tracking control script was tested to validate that the system is able to track and point towards the Sun accurately based on real-time calculations. The terminal output shows that the gimbal angles are continuously updated according to the Sun’s position computed using the Skyfield library. During testing the gimbal was observed to physically align with the direction of the Sun which confirms that the tracking algorithm is functioning as intended. A cross-check was also performed using SunCalc and the calculated azimuth and elevation angles were found to match closely with the system output which further verifies the accuracy of the tracking implementation.

8. Overall software operation flow

Software operation flow chart

Above is the overall operational flow of the gimbal control software. Detailed procedures for running the tracking scripts using TLE data and determining satellite pass windows are provided on our project website and documented in the interim report.

9. Future Works

1. The control algorithms can be further tuned and refined to improve tracking accuracy once testing is conducted with the actual mechanical system. This will allow better calibration between the software output and the physical gimbal response and will be implemented in future updates beyond the scope of this report.