Off-Axis Control Software

Introduction

The oacserver is the motion control and temperature/humidity monitoring software for the AIP AGW units. It runs on the computer oac.mountain.lbto.org. You need to log into oac to look at the log file, to download 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 oac.tucson.lbto.org, the simulator. Make sure where you landed before making conclusions.

ssh telescope@obs3.mountain.lbto.org
password: xxxx
ssh oac@oac.mountain.lbto.org

API developer documentation from AIP - http://telemetry.lbto.org/oac-doc/

Recap sketch of the different AGW and Camera controller flavors

• recap sketch

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. 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.

Build/Installation

The software is on GitHub.

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 install.sh builds and installs the software into /lbt/oacontrol/vvv/ where vvv is the version number and is specified to install.sh:

cd <working copy>
./install.sh 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: oac.mountain.lbto.org
The Tucson oac machine is a CentOS 7, 64-bit environment.

It builds a set of executables, including:

oacserver
startAGW
stopAGW
getdata
... 

And a library, the GCS links to: liboacontrol.so

Version

Version 5.0 was released in Aug-2018 with the updates for housekeeping using the 8051 board. Version 5.2 was released in March 2019 with imporved log formatting and AGW3 and AGW4 EPICS channel access for ALH.

Upgrades

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.

init	with AGW_START/AGW_STOP
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; }data;
getfocus setfocus
getfilter setfilter
getxy setxy
AGWgenericToSFP SFPToAGWgeneric
CCDgenericToSFP SFPToCCDgeneric
home
gethomestatus
getpowerstatus
stopmotion
sboardreset

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 downloading 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

P1111=1*10000+2*100+01

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

Each AGW unit has a set of common files, plus one unit specific file. The common files are

Control_Focus.pmc
Control_Stepper.pmc
Control_XY.pmc
errors.pmc
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 downloading into AGW1 with an old processor.

makefirmware_newDPRAM 1 201

will create AGW1_201_newDPRAM.cfg which is ready for downloading 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 download: agw78conf_last2download.dld. The scripts add this on the end of the .cfg file for units 7 and 8.

Downloading firmware

After the *.cfg file is made, it must be downloaded into the AGW and saved in ROM:

ssh telescope@obs<n>.mountain.lbto.org
Password: xxxx
ssh oac@oac
cd trunk/pmac_fw

uploadPMACConfig -u <UMAC> -f <file>
pmacsend -u <UMAC>
SAVE
$$$
e

where -u <UMAC> is the unit number (1,2,3,4,7,8), and -f <file> is the file to load. Note that the UMAC people call loading firmware an "upload" while the rest of us call it a "download". The pmacsend command starts a dialog with the UMAC. The SAVE command writes the downloaded file into ROM, the $$$ reboots the UMAC, and the e command exits pmacsend. For example, to load AGW1 for an old processor do

ssh telescope@obs3.mountain.lbto.org
Password: xxxx
ssh oac@oac

uploadPMACConfig -u 1 -f AGW1_201.cfg
pmacsend -u 1
SAVE
$$$
e

Note that the pmacsend program requires the oacontrol program to communicate with the UMAC.

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 downloaded 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>
SAVE
$$$
e

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