**STEREO/HET & STEREO/SIT**

> **Serial Command Interface:**
>
> **Programmer and User Guide for**
>
> **Build 1 -- WinMac Version 1a**
>
> September 19, 2002
>
> *Prepared by:\
> * Kristin Wortman
>
> Computer Sciences Corporation

[Table of Contents]{.underline}

[**Background 3**](#background)

[Overview 3](#overview)

[References 3](#references)

[Modifications to the WinMac Software for HET Serial Commanding
(Build 1)
4](#modifications-to-the-winmac-software-for-het-serial-commanding-build-1)

[Operating Environment 7](#operating-environment)

[TCP/IP Communications 8](#tcpip-communications)

[STEREO/HET TCP/IP Packet Format (In-House Testing)
9](#__RefHeading___Toc20284142)

[STEREO/HET Pulse Height Data Format
10](#stereohet-pulse-height-data-format)

[GSE Commanding Dialog for HET 11](#gse-commanding-dialog-for-het)

[Setting up the STEREO/HET Serial Command Register
11](#setting-up-the-stereohet-serial-command-register)

[Sending the Serial Command via TCP/IP
16](#sending-the-serial-command-via-tcpip)

[Sending the Rates Command via TCP/IP
17](#sending-the-rates-command-via-tcpip)

[Saving and Loading a Command Setup to a File
17](#saving-and-loading-a-command-setup-to-a-file)

[Establishing the TCP/IP Connection
18](#establishing-the-tcpip-connection)

[Telemetry Data Collection via TCP/IP
19](#telemetry-data-collection-via-tcpip)

[Displaying the Data Packets 20](#displaying-the-data-packets)

[Controlling the Display Rate 20](#controlling-the-display-rate)

[Limitations of the Serial Command Interface Feature
21](#limitations-of-the-serial-command-interface-feature)

#  

# Background

An existing software program, referred to as WinMac, was originally
developed for the low energy cosmic ray group (LECR) for scientific
graphical analysis of instrument telemetry data. The original design
philosophy was based on the original Macro program (DOS command line
version), which was written by Dr. Donald Reames, NASA/GSFC.

# Overview

The WinMac software is written in the C++ programming language using
object-oriented methodologies and the Microsoft Foundation Class (MFC)
library. Using the MFC library enables point and click technology and a
Windows graphical user interface through a series of menus and dialogs.

WinMac reads instrument telemetry data files, which have been produced
following the guidelines used for the LECR data file format. The WinMac
software produces 2 and 3 dimensional plots, which are used for
interactive analysis efforts by the NASA scientists in the preparation
of research papers.

# References

STEREO PHA Chip User's Manual, Rick Cook, (CalTech)

Serial Port Interface to TCP/IP (SPiT), Tom Nolan

PHA Test Software, Tom Nolan

LECR Data File Format, Don Reames (NASA/GSFC), Kristin Wortman (CSC)

<http://epact2.gsfc.nasa.gov/STEREO/docs.html>

# Modifications to the WinMac Software for HET Serial Commanding (Build 1)

In order to support the HET serial commanding the following additional
features were added to the WinMac Software:

-   TCP/IP communications with the server-side software, referred to as
    Serial Port Interface to TCP/IP (SPiT).

-   Send commands in ASCII HEX string via TCP/IP.

-   Receive telemetry packets via TCP/IP.

-   Create binary telemetry data files in the LECR format.

-   Receive command responses via TCP/IP.

-   Display telemetry packets in readable format according to bit
    addressing scheme.

-   Setup each HET serial command bit assignment via a series of menus
    and dialogs.

-   Provide an ASCII text data file, which shows the commanding session
    activity.

The following diagram shows the design of the serial commanding feature.

![](media/image1.png){width="6.125in" height="8.125in"}

> **Serial Command Feature Data Flow Diagram**

The following table shows the command list format, which is used to
identify and transmit the serial commands over the TCP/IP protocol to
the server side program, SPiT.

  ----------------------- ----------------------- -----------------------
  **Keyword**             **Argument**            **Function**

  cmdstr                  108 hex bytes (216      846-byte command string
                          characters)             (left-aligned) plus 18
                                                  bits (zeros)

  testp                   test pulser period      Set test pulser period.
                          (hex)                   Argument is in hex,
                                                  units of 2 microsecs.

  rates                                           Read and clear rates.
  ----------------------- ----------------------- -----------------------

**STEREO/HET Serial Commands**

The following communications protocol was established and is used in the
SPIT and WinMac software.

+----------------------+-----------------------+-----------------------+
| **Opcode**           | **Parameters**        | **Description**       |
+----------------------+-----------------------+-----------------------+
| OP_SES (1)           | SES_SNDCMD (0x10)     | Send commands         |
|                      |                       |                       |
|                      | SES_RCVCMD (0x20)     | Receive command       |
|                      |                       | response              |
|                      | SES_RCVTLM (0x40)     |                       |
|                      |                       | Receives telemetry    |
+----------------------+-----------------------+-----------------------+
| OP_CMD               | 0                     | Command for delivery  |
|                      |                       | to instrument         |
+----------------------+-----------------------+-----------------------+
| OP_RSP               | 0                     | Command response from |
|                      |                       | instrument            |
+----------------------+-----------------------+-----------------------+
| OP_TLM               | 0                     | Receive telemetry     |
|                      |                       | packet from           |
|                      |                       | instrument            |
+----------------------+-----------------------+-----------------------+

**Communications Protocol for SPIT and WinMac Software**

# Operating Environment

The serial command interface operates in the following software/hardware
environment, where GSE-1, GSE-2 and GSE-3 show how the WinMac software
can be used to communicate with the SpiT software, which in turn
communicates with the software executing on the 24-bit microprocessor
(MISC), which communicates directly with the PHA ASICS chip via a direct
serial link connection.

![](media/image2.png){width="6.707638888888889in"
height="4.218055555555556in"}

# TCP/IP Communications

The WinMac serial command interface uses the TCP/IP protocol for
communications with the SPiT software to send and receive commands and
data. The following software routines are used in the WinMac and the
SpiT software to accomplish this bi-directional communication.

![](media/image3.png){width="6.197222222222222in"
height="2.957638888888889in"}

![](media/image4.png){width="6.238888888888889in"
height="4.027777777777778in"}

![](media/image5.png){width="6.249305555555556in"
height="1.2395833333333333in"}

[]{#__RefHeading___Toc20284142 .anchor}**STEREO/HET TCP/IP Packet Format
(In-House Testing)**

In order to perform in-house testing of the PHA ASICS chip, the
following STEREO/HET packet format was designed and is used as input,
over the TCP/IP protocol, to the WinMac software.

  ----------- ------------ -----------------------------------------------
  **Offset    **Size       **Contents**
  (bytes)**   (bytes)**    

  0           11           CCSDS Header

  11          1            Packet type (0xe9 event, 0xad rate)

  12          1            Sequence number (increments by 1)

  13          1            Number of 24-bit words (0-86)

  14          258          24-bit ph or rate words (lsb -- msb)
  ----------- ------------ -----------------------------------------------

# 

# 

# 

# STEREO/HET Pulse Height Data Format

The STEREO/HET pulse height data for in-house testing is received in a
compressed 24-bit format and is described in the structure below.

> struct COMP_PH
>
> {
>
> unsigned ph : 11; // bits 0-10
>
> unsigned overflow : 1; // bit 11
>
> unsigned reserved1 : 1; // bit 12
>
> unsigned reserved2 : 1; // bit 13
>
> unsigned lohigain : 1; // bit 14
>
> unsigned pha_addr : 4; // bits 15-18
>
> unsigned chip_addr : 4; // bits 19-2
>
> unsigned token : 1; // bit 23
>
> };

COMP_PH \*c;

WinMac receives the compressed STEREO/HET pulse height data in the
packets and in order to display the values, it is necessary to
uncompress the data according to the following structure.

struct UNCOMP_PH

{

unsigned short verse;

short byte_cnt;

unsigned short ph;

unsigned short overflow;

unsigned short reserved1;

unsigned short reserved2;

unsigned short lohigain;

unsigned short pha_addr;

unsigned short chip_addr;

unsigned short token;

};

UNCOMP_PH \*u;

# GSE Commanding Dialog for HET

To invoke the HET serial commanding option in the WinMac application,
simply click the WinMac icon located on the desktop and select the
**Communications \| HET GSE** option located on the main menu. Refer to
following illustration:

![](media/image6.png){width="5.28125in" height="1.46875in"}

# Setting up the STEREO/HET Serial Command Register

The STEREO/HET serial command register consists of 846 bits. Bit
assignments are assigned according to the following table, which is
explained in the STEREO PHA Chip User\'s Manual written by Rick Cook
(CalTech).

category PHA# bit names \# of bits

Scope-mux n/a scopesel7,\...,0, scope-enable 9

Preout-mux n/a presel3,2,1,0, preout-enable 5

Test pulse/feedback PHA0,\...,15 test-enable, testsel3,2,1,0,
fbsel3,2,1,0 9\*16

Input resistance, etc. PHA15,\...,0 rdgsel2,1,0, indac9,\...,0 13\*16

Threshold setting PHA0H,\...,15L ioff9,\...,0 10\*32

PHA control PHA15,\...,0 hg-adc-en, lg-adc-en, verbose, power-on 4\*16

rndn-gor-0 n/a enable-rndn15L,\...,enable-rndn0H 32

rndn-gor-1 n/a enable-rndn15L,\...,enable-rndn0H 32

rndn-gor-2 n/a enable-rndn15L,\...,enable-rndn0H 32

Total \# of bits: 846

**Command Register Bit Assignments**

In order to simplify the setup of the command register, a series of pull
down menus and dialogs are used to set the values in the corresponding
bits. After invoking the HET GSE option from the WinMac main menu, the
following dialog will be displayed on the screen.

![](media/image7.png){width="5.041666666666667in"
height="4.552083333333333in"}

The GSE commanding dialog provides all the necessary options to setup
the command register, send the commands, and view the session activity
and to start data collection to create data files. All this
functionality is accomplished by the following features:

-   Pull down menus for setup of command bit assignments

-   Selectable command lists for sending the following commands:

    -   cmdstr

    -   rates

    -   testp

-   Button to send current command

-   Buttons to start & stop telemetry data collection

-   Command string display

-   Session log display and data file (command.log)

-   Button to control the display rate

-   Buttons to save and load command setups to and from files

The GSE commanding dialog's main menu contains options with submenu
items for choosing the desired bit assignments.

![](media/image8.png){width="4.979166666666667in" height="0.625in"}

For example, to set the **test pulse input**, the following selection
would be made from the above GSE commanding dialog's menu.

![](media/image9.png){width="5.020833333333333in" height="0.90625in"}

At which point, the following dialog would be displayed:

![](media/image10.png){width="2.897222222222222in"
height="4.822916666666667in"}

This dialog is an example of the command register's bit assignments,
which use a fixed range of values. These values are selectable for each
pulse height channel. An additional feature allows a value to be
selected and used for setting all the pulse height channels with just
one command, a global setting/resetting.

Different types of dialogs are used, based on the type of bit
assignments needed in the command register. This type of dialog is used
for manually entering a value (for setting high gain thresholds) as
follows:

![](media/image11.png){width="2.9340277777777777in"
height="4.188194444444444in"}

In some cases, it is necessary to toggle (on/off) one bit in the command
register; the following is an example of the dialog used:

![](media/image12.png){width="2.75in" height="4.267361111111111in"}

As you setup the command register bits, the command display will update
and can be referenced to view all the current bit assignments as
follows:

![](media/image13.png){width="4.032638888888889in"
height="2.6354166666666665in"}

This is a scrollable display, the date and time will update after each
change has been made to the serial command bits.

# 

# Sending the Serial Command via TCP/IP

Once the command string setup has been completed and you are ready to
send the command via TCP/IP to the SPiT program, you need to select
***cmdstr*** from the following selectable list (located on the GSE
Commanding dialog) as follows:

![](media/image14.png){width="1.0416666666666667in" height="1.59375in"}

After selecting ***cmdstr***, you simple click on the **SEND** button.
At which point, you will notice that the command has been echoed in the
command log display in the ASCII HEX format, as follows:

![](media/image15.png){width="3.6347222222222224in"
height="1.2708333333333333in"}

# 

# 

# 

# 

# Sending the Rates Command via TCP/IP

To send the rates command to the PHA ASICS chip, you need to select
***rates*** from the following selectable list (located on the GSE
Commanding dialog) as follows:

![](media/image16.png){width="1.0833333333333333in"
height="1.6666666666666667in"}

After selecting ***rates***, you simple click on the **SEND** button. At
which point, you will notice that the command has been echoed in the
command log display, as follows:

![](media/image17.png){width="3.6354166666666665in"
height="1.3229166666666667in"}

# Saving and Loading a Command Setup to a File

Once a command has been setup, you can save this command to a file and
load it back in at a later time. Simply click on the **SAVE** button
which will bring up the standard Windows ***SAVE AS*** dialog to prompt
you for a filename using the extension .cmd.

When you want to load the command, simply click on the **LOAD** button
which will bring up the standard Windows ***OPEN*** dialog to prompt you
for an existing filename with the extension .cmd.

# 

# Establishing the TCP/IP Connection

WinMac automatically detects the first time the TCP/IP connection is
needed; this is done by the first selection of the **SEND** or **DATA**
button. At this time, the following dialog will be displayed to request
the IP address of the computer to connect to and its port number. In
addition, a LECR formatted header file also needs to be provided. This
header file describes the LECR data and is used for the display and
plotting routines.

![](media/image18.png){width="3.75in" height="2.9680555555555554in"}

The default IP address and port identification number are read in from
the ***WinSock.ini*** file, which is created and read each time you
invoke this dialog. If the file does not exist, a hard coded loop back
IP address and port number are used.

# 

# 

# 

# Telemetry Data Collection via TCP/IP 

The HET GSE commanding option contains the controls to start and stop
data collection of telemetry packets over the TCP/IP protocol. Telemetry
packets will be received from the SPiT software and written to a binary
data file that can be read for display and plotting by the WinMac
program at a later time.

To invoke data collection, the **DATA** button which is located on the
HET GSE commanding dialog is used.

![](media/image19.png){width="0.9791666666666666in"
height="0.7708333333333334in"}

As a result of pressing the **DATA** button , the Windows standard
***SAVE AS*** dialog will be displayed and request you to enter a file
name to store the telemetry packets. The following is an example of what
you will see:

![](media/image20.png){width="4.427083333333333in"
height="2.8229166666666665in"}

Selecting the **DATA** button when telemetry data is already being
collected will stop data collection to the currently selected file. The
***SAVE AS*** dialog will be displayed to prompt you for a new file name
and then data collection will start again.

Termination of data collection can also be accomplished by selecting the
**DISCONNECT** button located on the GSE Commanding dialog.

# Displaying the Data Packets

The WinMac software is capable of displaying the data packets, which
have been previously collected using TCP/IP and written to a LECR
formatted file. To invoke the display for HET pulse height and rate
packets, follow these steps:

-   Click on the client area of the WinMac program, this is the white
    space located to the left of the HET GSE commanding dialog.

-   Press **G** on the keyboard.

-   To stop displaying the data packets, hit the **ESC** button.

Here is an example of what you will see when this option has been
properly invoked:

> ![](media/image21.png){width="5.856944444444444in" height="3.45in"}

To the right top of the display, you will notice the number of events
and packets are displayed, along with the current status of the data
collection. There are three possible states: ***Waiting, Running*** and
***Disconnected.***

# Controlling the Display Rate

Since the data packets are being read from a data file, the speed of the
computer can affect the rate at which the packets are displayed. In
order to simulate the real time, a higher speed CPU is needed. However,
it may be necessary to view the contents of the display at a much slower
rate. To change the display rate, you can enter a value in microseconds.
This is done using the following control located on the HET GSE
commanding dialog:

![](media/image22.png){width="1.0326388888888889in"
height="0.7034722222222223in"}

# Limitations of the Serial Command Interface Feature

WinMac Version 1a, which contains the serial command interface feature
for STEREO/HET, is capable of supporting only one GSE commanding
session, which is connected to one IP address and port for in-house
testing of the PHA ASICS chip. Since WinMac Version 1a is capable of
multiple panel displays, the first panel display is reserved for the HET
GSE commanding session, however additional displays can be created,
setup and used for plotting the telemetry data.

In order to keep the commanding session active, the HET GSE commanding
dialog needs to remain active throughout the WinMac session. Termination
of this dialog will also terminate any active TCP/IP connection.

The CPU speed of the computer will affect the display rate of the data
packets. It is recommended that a minimum of a 1.0 GHz processor be used
running Windows 2000/XP operating system.