You are here: Foswiki>Software Web>OAC (09 Oct 2020, CarlHolmberg)Edit Attach

Off-Axis Control Software


The oacserver is the motion control and temperature/humidity monitoring software for the AIP AGW units. It runs on the computer You need to log into oac to look at the log file, to upload firmware, and to restart the software. To access oac, log into any of the mountain obs computers as user telescope, and then ssh to oac as user oac. There is no password on oac. Please note there is also, the development machine. Make sure where you landed before making conclusions.

%CODE{lang="sh"}% ssh password: xxxx ssh %ENDCODE%

API developer documentation from AIP -

Coordinate transformations

GS to probe (for guider probe positioning on guide star (GS)):

  1. PCS:computeKFPCoordinates transfers GS RADEC in KFP mm; that uses rotator angle and simple scaling attached to tpk::AutoGuider
  2. SFPtoAGWgeneric to transform to AGW x,y
  3. AGW translate x y into R,Theta polar coordinates using UMAC configuration (UMAC knows how to transfer from x,y to native coordinates)

Operations and Troubleshooting

  • The commissioning wiki page, Operating the AGw Units, contains detailed notes for how to tell if it is running correctly, how to restart, where the logs are, RPC errors, etc.

  • The oacserver on computer oac writes the log file /var/log/oacontrol.log (version 5.0 and lower) or to files under /lbt/log/oac (version 5.1 and higher). Always look at the log file during troubleshooting. A command may fail, but not report on the command line or to GCS what the actual problems were.

  • There are separate RPC programs for each AGW, for each command (currently 25 for each AGW) - all are uniquely numbered (see the .x files in the source) with the AGW number appended (AGW number -1 since it starts at 0). For example: 2018003 is registered as the getAGWData program for AGW 4.

  • The timeout values for each of the RPC programs are defined in the xxx_clnt.c file and most are set to 3 seconds.

  • Compile with SIMULATOR defined if you want to test without a UMAC available.

  • Compile with DEBUG if you want more logging.


The software is in SVN in

The make environment has been changed to look like the TCS make environment, so just a make at the top-level is required to build locally. The script builds and installs the software into /lbt/oacontrol/vvv/ where vvv is the version number and is specified to
cd <working copy>
./ 4.4

The build requires the LBTO telemetry collection library and EPICS (ezca).

The mountain has a CentOS 6.5, 32-bit environment - the operational version is built on the mountain:
The Tucson oac machine is a CentOS 7, 64-bit environment.

It builds a set of executables, including:

And a library, the GCS links to:


Version 5.0 was released in Aug-2018 with the updates for housekeeping using the 8051 board.


See OAControlSoftwareUpgrades for notes on requested upgrades and current bugs, etc.

GCS Interface

GCS interfaces to the oacserver using RPC. The AIP AGw units call the following APIs.

getdata returns a struct of info:
typedef struct data {
        /** General state of AGW unit */
        int general_state;
        /** Errors on AGW unit */
        int general_errors;
        /** State of the rotational axis */
        int my_state;
        /** Errors regarding the rotational axis */
        int my_errors;
        /** State of the radial axis */
        int mx_state;
        /** Errors regarding the radial axis */
        int mx_errors;
        /** State of the focus axis */
        int mf_state;
        /** Errors regarding the focus axis */
        int mf_errors;
        /** State of the filter wheel axis */
        int mw_state;
        /** Errors regarding the filter wheel axis */
        int mw_errors;
        /** Temperature in the E-Box of AGW unit */
        int temp_umac;
        /** Temperature outside the E-Box of AGW unit */
        int temp_outside;
        /** Humidity in the E-Box of AGW unit */
        int hum_umac;
        /** Version number for oacontrol */
        struct {
                unsigned int oacversion_len;
                char *oacversion_val;
        } oacversion;
The oacserver uses the "1-wire" filesystem to get housekeeping data from the AGw (the getdata functionality of the RPC interface).

The other RPC functions are implemented through PMAC functions.

AGw firmware

Each AIP AGw unit has device specific firmware. The firmware files are kept in SVN under .../oacontrol/pmac_fw/. This directory can be on any available computer, but the only place it is sure to be is on the computer oac. There are three types of files: *.pmc, *.dld, and *.cfg. The *.pmc files are source code, using #define statements to associate symbolic names with UMAC register names. The *.pmc files are processed into *.dld files by converting the symbolic names to UMAC register names using the C preprocessor. Some of the *.dld files do not have corresponding *.pmc files, and are maintained by hand. The *.cfg files are ready for uploading into a UMAC. There are shell scripts makefirmware and makefirmware_newDPRAM that take all the input files, generate the .dld files, and concatenate the appropriate .dld files into the final .cfg file.

We are replacing the two-board PMAC processors with a newer one-board PMAC processor. When that happens, the handling of the dual-port RAM (DPRAM) in the processor changes. DPRAM addresses of $6Cxxx must be changed to $60xxx. We have replaced the processors in AGW3 and AGW4, but not AGW1, AGW2, AGW7, or AGW8 (AGW7 and AGW8 need to be verified, but I'm pretty sure).

Some .pmc and .dld files have two versions, one with _newDPRAM., to support the newer processor. The script makefirmware generates the code for the old processor, and makefirmware_newDPRAM generates the code for the newer processor.

Version number

The final *.cfg file has the unit number and version number stored in UMAC register P1111 as <unit> * 10000 + <ver> * 100 + <subver>. For example AGW1 version 2.01 has

This is hard coded into file AGWn_vvv.dld and should be changed whenever changes are made to the firmware. The most likely reason is changing servo parameters. Note that only AGW3 and AGW4 have been loaded with firmware generated as described here. AGW1, AGW2, AGW7, and AGW8 have firmware that does not include the version number, even though servo parameters were changed in 2014 for AGW1 and AGW2.

Files & Making firmware

Each AGW unit has a set of common files, plus one unit specific file. The common files are
plc1.pmc (plc1_newDPRAM.pmc)
config_agw_pmac.dld (config_agw_pmac_newDPRAM.dld)

The unit specific file is AGWn_vvv.dld, where n is the unit number (1,2,3,4,7,8) and vvv is the firmware version number (currently 201 for version 2.01). The unit specific file mostly contains servo tuning parameters.

The script makefirmware (makefirmware_newDPRAM) is invoked with the unit number and version:

makefirmware 1 201

will create AGW1_201.cfg which is ready for uploading into AGW1 with an old processor.

makefirmware_newDPRAM 1 201

will create AGW1_201_newDPRAM.cfg which is ready for uploading into AGW1 with a newer processor.

The scripts generate .dld files from .pmc files, and those generated files are not kept in SVN. Other .dld files not generated from .pmc files are kept in SVN. See the makefirmware scripts to see how sed and the preprocessor are used to convert the .pmc files.

AGW7 and AGW8

These units are for the PEPSI PFU, and do not have an XY stage. There is one additional file that must be included in the upload: agw78conf_last2download.dld. The scripts add this on the end of the .cfg file for units 7 and 8.

Uploading firmware from scratch, processor initial load

Before using a processor (either flavor) for the first time, the file config_agw_pmac.dld (config_agw_pmac_newDPRAM.dld) must be uploaded first (same file for all units). This establishes much of the common code, is fairly long, but is only done once. For example, to initialize a new style processor for first time use do

uploadPMACConfig -u <UMAC> -f config_agw_pmac_newDPRAM.dld
pmacsend -u <UMAC>

Now load the unit specific .cfg file as described below.

Uploading unit specific firmware

After building a unit specific *.cfg file using makefirmware or makefirmware_newDPRAM, it must be uploaded into the AGW and saved in ROM:

ssh telescope@obs<n>
Password: xxxx
ssh oac@oac
cd trunk/pmac_fw

uploadPMACConfig -u <UMAC> -f <file>
pmacsend -u <UMAC>

where -u <UMAC> is the unit number (1,2,3,4,7,8), and -f <file> is the file to load. The pmacsend command starts a dialog with the UMAC. The SAVE command writes the uploaded file into ROM, the $$$ reboots the UMAC, and the e command exits pmacsend. For example, to load AGW1 for an old processor do

Password: xxxx
ssh oac@oac

uploadPMACConfig -u 1 -f AGW1_201.cfg
pmacsend -u 1

Note that the pmacsend program requires the oacontrol program to communicate with the UMAC.
Topic revision: r23 - 09 Oct 2020, CarlHolmberg
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback