EIR-OPS-018: Rewrite CPLD Firmware

Objective

To write firmware to the GMOD CPLD.

Introduction

Using this procedure, the Operator will write a new firmware image to the GMOD CPLD.

Procedure

This procedure has the following subsections:

A. Pre-pass Preparations
B. Upload New CPLD Firmware to OBC
C. Rewrite Preparations
D. Reprogramming the CPLD
E. Post-Programming

Note

A communication window is required for all steps in Sections B - E of this procedure.

A. Pre-pass Preparations

A.1.

Prior to the first pass in which Section B is followed, the Operators must ensure they have access to:
- The CPLD image to be uplinked (needed for Steps A.2 and B.6),
- An MD5 checksum for this image (Step C.16), and
- The length of the image in rows (Steps B.6, B.8, C.14, C.15 and D.5).

Warning

The image to be uplinked must be located on the same computer as MCS (or at least a file system that MCS can access).

A.2.

Calculate an MD5 checksum for the image to be uplinked using:
- certutil -hashfile <file> MD5 in a terminal on a windows computer, or
- md5 <file> in a terminal on a Mac.
Ensure this checksum matches the checksum from the previous step.

B. Upload New CPLD Firmware to OBC

Important

You are about to send the first TC of this procedure - Have you completed the EIR-OPS-003: Start a Communication Pass procedure? A Communication Pass must be started prior to carrying out the operations planned for the pass. Don’t forget to open and set-up the parameters/actions that will be required before the pass starts!

B.1.

The storage channel on the OBC that is intended for CPLD image uploads is 85 (dec).
Before uplinking this firmware to the spacecraft, assess whether the storage channel you intend to fill is empty. To do this:
- Query the parameter core.storage.channelContent with Parameter index in block = 85 (dec).

TC Details
MCS Operation	`Query`
Action/Param Name	`core.storage.channelContent`
Data Expected with TC	`Parameter index in block`
Data Size	2 bytes
Data Info	The ChID of storage channel
Allowed Value(s)	0001 - FFFF (Hex)
Expected Value(s)	85 (dec)
TM Details
Data Expected from TC	`rows` ( + ACK )
Data Size	2 bytes
Data Info	The number of rows of data in ChID
Allowed Value(s)	0000 - FFFF (Hex)

B.2.

If 0 is returned from the previous step, the Operator can now proceed to Step B.4.
Else, data is already occupying this storage channel. Therefore:
- The Operator should now consult with the Software Engineer to confirm it is ok to wipe this data from the channel.
- If the Software Engineer gives permission, the Operator should Invoke the action core.storage.Wipe with action argument = 85 (dec).

TC Details
MCS Operation	`Invoke`
Action/Param Name	`core.storage.Wipe`
Data Expected with TC	`ChannelID`
Data Size	2 bytes
Data Info	The ID of the storage channel you wish to wipe
Allowed Value(s)	0001 - FFFF (Hex)
Expected Value(s)	85 (dec)
TM Details
Data Expected from TC	No ( + ACK )

B.3.

Query the parameter core.storage.channelContent with Parameter index in block = 85 (dec).
Confirm 0 (rows) is returned to confirm the wipe was successful.

TC Details
MCS Operation	`Query`
Action/Param Name	`core.storage.channelContent`
Data Expected with TC	`Parameter index in block`
Data Size	2 bytes
Data Info	The ChID of storage channel
Allowed Value(s)	0001 - FFFF (Hex)
Expected Value(s)	85 (dec)
TM Details
Data Expected from TC	`rows` ( + ACK )
Data Size	2 bytes
Data Info	The number of rows of data in ChID
Allowed Value(s)	0000 - FFFF (Hex)
Expected Value	0000

B.4.

Set the parameter core.storage.rowLength to 41 (dec) with First Row = Last Row = 85 (dec).

TC Details
MCS Operation	`Set`
Action/Param Name	`core.storage.rowLength`
Data Expected with TC	`First Row` , `Last Row` , `rowLength`
Data Size	4 bytes, 4 bytes, 4 bytes
Data Info	The range of ChIDs and row length to set
Allowed Value(s)	0 - 87 (dec), 0 - 87 (dec), 00000000 - FFFFFFFF (hex)
Expected Value(s)	`First Row` = `Last Row` = 85 (dec), 41 (dec)
TM Details
Data Expected from TC	No ( + ACK )

B.5.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

B.6.

Important

As you are about to perform a large uplink of data to the spacecraft, ensure that MCS’s Transfer Window is visible to the Operator before proceeding with this step.

The Operator can now Uplink GMOD’s CPLD image to the OBC flash channel using the parameter core.storage.channelContent , with:
- Parameter index in block = 85 (dec),
- First row = 0,
- Last row = the length of the image in rows (from Section A) - 1, and
- Resize ticked.

TC Details
MCS Operation	`Uplink`
Action/Param Name	`core.storage.channelContent`
Data Expected with TC	`Parameter index in block` , `First row` , `Last row` , binary file , `Resize`
Data Size	4 bytes , 4 bytes , 4 bytes , many bytes, 1 byte
Data Info	The ChID to uplink to, the row range to be written to, the image to uplink, whether the file should be resized into rows
Allowed Value(s)	1-87 (dec), 00000000-FFFFFFFF (hex), 00000000-FFFFFFFF (hex), N/A, 0-1
Expected Value(s)	85 (dec), 0, length of the image in rows - 1, binary file from Section A, 1
TM Details
Data Expected from TC	No ( + ACK )

B.7.

Wait for the Transfer Window on MCS to indicate that the uplink has completed successfully.

Note

Uplinking the image to the spacecraft may require multiple communication passes. At the end of each pass, MCS will automatically ‘Suspend’ the transfer. At the start of each pass, the Operator should ‘Resume’ the transfer after completing the EIR-OPS-003: Start a Communication Pass procedure.

B.8.

Query the parameter core.storage.channelContent with Parameter index in block = 85 (dec).
Ensure the TM returned = the length of the image in rows (from Section A).

TC Details
MCS Operation	`Query`
Action/Param Name	`core.storage.channelContent`
Data Expected with TC	`Parameter index in block`
Data Size	2 bytes
Data Info	The ChID of storage channel
Allowed Value(s)	0001 - FFFF (Hex)
Expected Value(s)	85 (Dec)
TM Details
Data Expected from TC	`rows` ( + ACK )
Data Size	2 bytes
Data Info	The number of rows of data in ChID
Allowed Value(s)	0000 - FFFF (Hex)
Expected Value	The length of the image in rows from Section A

C. Rewrite Preparations

C.1.

Get the platform.EPS.actualSwitchStates parameter, with First row = 0 and Last row = 9.
Assess the status of rows 2, 5 and 8 of this parameter (i.e. PDMs 3, 6 and 9).
If 1 is returned for these rows/PDMs, the MSP is on.

Warning

PDM 8 (i.e. row 7 of this parameter) is drawing parasitic power. Therefore, when you Get the platform.EPS.actualSwitchStates parameter it will always read as on/1 even when it is powered off.

TC Details
MCS Operation	`Get`
Action/Param Name	`platform.EPS.actualSwitchStates`
Data Expected with TC	Yes
Data Size	2 bytes, 2 bytes
Data Info	`First Row` , `Last Row`
Allowed Value(s)	0-9, 0-9
Expected Value(s)	0, 9
TM Details
Data Expected from TC	`actualSwitchStates` ( + ACK )
Data Size	List[0:9] of Booleans
Data Info	SwitchState = 0 (Off), SwitchState = 1 (On)
Allowed Value(s)	0 or 1 for each row/PDM

C.2.

If the above step shows that the MSP is on, proceed to Step C.4.
Else, if one or more of the MSP’s PDMs are powered off, Invoke the platform.EPS.TurnOnGMOD action.

TC Details
MCS Operation	`Invoke`
Action/Param Name	`platform.EPS.TurnOnGMOD`
Data Expected with TC	No
TM Details
Data Expected from TC	No ( + ACK )

C.3.

To confirm that the MSP is now powered on, Get the platform.EPS.actualSwitchStates parameter, with First row = 0 and Last row = 9.
Ensure that rows 2, 5 and 8 of this parameter (i.e. PDMs 3, 6 and 9) now equal 1.

Warning

PDM 8 (i.e. row 7 of this parameter) is drawing parasitic power. Therefore, when you Get the platform.EPS.actualSwitchStates parameter it will always read as on/1 even when it is powered off.

TC Details
MCS Operation	`Get`
Action/Param Name	`platform.EPS.actualSwitchStates`
Data Expected with TC	Yes
Data Size	2 bytes, 2 bytes
Data Info	`First Row` , `Last Row`
Allowed Value(s)	0-9, 0-9
Expected Value(s)	0, 9
TM Details
Data Expected from TC	`actualSwitchStates` ( + ACK )
Data Size	List[0:9] of Booleans
Data Info	SwitchState = 0 (Off), SwitchState = 1 (On)
Allowed Value(s)	0 or 1 for each switch
Expected Value(s)	XX1XX1XX1X (i.e. PDMs 3, 6 and 9 = 1, other PDMs can be 0 or 1)

C.4.

Get the payload.GMOD.GMODMode parameter to assess which mode the firmware running on the MSP is operating in.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.GMODMode`
Data Expected with TC	No
TM Details
Data Expected from TC	`GMODMode` ( + ACK )
Data Size	1 byte
Data Info	Payload operational mode
Allowed Value(s)	See table below

Where…

Firmware	`Mode`	Mode
GMOD	1	Idle
GMOD	2	Experiment
GMOD	3	CPLD
GMOD	4	Safe

C.5.

If the payload.GMOD.GMODMode parameter indicates that Idle Mode is on-going, skip ahead to Step C.7.
Else, now Set the GMODMode parameter to 1/Idle Mode.

TC Details
MCS Operation	`Set`
Action/Param Name	`payload.GMOD.GMODMode`
Data Expected with TC	Yes
Data Size	1 byte
Data Info	The mode to set EMOD to
Allowed Value(s)	0-1
Expected Value(s)	1
TM Details
Data Expected from TC	No ( + ACK )

C.6.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

Tip

It may take the payload MSP ~tens of seconds to complete the mode change.

C.7.

Get the platform.obc.GMODSerial.baudRateParam parameter.

TC Details
MCS Operation	`Get`
Action/Param Name	`platform.obc.GMODSerial.baudRateParam`
Data Expected with TC	No
TM Details
Data Expected from TC	`baudRateParam` ( + ACK )
Data Size	4 bytes
Data Info	The baud rate used for GMOD serial communications
Allowed Value(s)	00000000 - FFFFFFFF (hex)

C.8.

If 128000 (dec) was returned in the previous step, the baud rate is already as desired. Therefore, skip ahead to Step C.10.
Else, Set the platform.obc.GMODSerial.baudRateParam parameter to 128000 (dec).

Warning

The Operator should be aware of the fact that multiple different SCDB paths are used for this procedure (i.e. payload.GMOD, platform.obc.GMODSerial and payload.FirmwareImageAccess). However, this is not a major concern as it will become obvious if an SCDB is mistaken as the parameter/action will only exist in the correct SCDB path.

TC Details
MCS Operation	`Set`
Action/Param Name	`platform.obc.GMODSerial.baudRateParam`
Data Expected with TC	Yes
Data Size	4 bytes
Data Info	The desired baud rate for GMOD serial communications
Allowed Value(s)	00000000 - FFFFFFFF (hex)
Expected Value(s)	128000 (dec)
TM Details
Data Expected from TC	No ( + ACK )

C.9.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

C.10.

To programme an image from the OBC onto the CPLD, the desired image must first be loaded from an OBC flash storage channel to a buffer. To start this process, first Set the payload.FirmwareImageAccess.ImageStorageChID parameter to 85 (dec).

TC Details
MCS Operation	`Set`
Action/Param Name	`payload.FirmwareImageAccess.ImageStorageChID`
Data Expected with TC	Yes
Data Size	2 bytes
Data Info	ID of the storage channel from where the firmware is to be loaded
Allowed Value(s)	0000 - FFFF (hex)
Expected Value(s)	85 (dec)
TM Details
Data Expected from TC	No ( + ACK )

C.11.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

C.12.

Next Invoke the payload.FirmwareImageAccess.ClearImageBuffer action to clear any previous data being held in the buffer.

TC Details
MCS Operation	`Invoke`
Action/Param Name	`payload.FirmwareImageAccess.ClearImageBuffer`
Data Expected with TC	No
TM Details
Data Expected from TC	No ( + ACK )

C.13.

To verify that the buffer is now cleared/empty, Query the payload.FirmwareImageAccess.ImageBuffer parameter.
Ensure that 0 (rows) is returned.

TC Details
MCS Operation	`Query`
Action/Param Name	`payload.FirmwareImageAccess.ImageBuffer`
Data Expected with TC	No
TM Details
Data Expected from TC	Rows ( + ACK )
Data Size	2 bytes
Data Info	The number of rows of data in the buffer
Allowed Value(s)	0000 - FFFF (Hex)
Expected Value	0

C.14.

Warning

MCS does not allow the Operator to provide a decimal action argument for the action in this step. Operators will need to input the action argument in hexadecimal format.

Invoke the payload.FirmwareImageAccess.LoadImageFromStorage action with the input argument, Last row = the size of the image in rows - 1 (refer to Section A for the size of the image in rows).

TC Details
MCS Operation	`Invoke`
Action/Param Name	`payload.FirmwareImageAccess.LoadImageFromStorage`
Data Expected with TC	Yes
Data Size	2 bytes
Data Info	`Last row` = (the size of the image in rows from Section A - 1)
TM Details
Data Expected from TC	No ( + ACK )

C.15.

Again Query the payload.FirmwareImageAccess.ImageBuffer parameter.
This time, ensure that the data returned = the size of the image in rows (refer to Section A for the size of the image in rows).

TC Details
MCS Operation	`Query`
Action/Param Name	`payload.FirmwareImageAccess.ImageBuffer`
Data Expected with TC	No
TM Details
Data Expected from TC	Rows ( + ACK )
Data Size	2 bytes
Data Info	The number of rows of data in the buffer
Allowed Value(s)	0000 - FFFF (Hex)
Expected Value	The size of the image in rows from Section A

C.16.

To further verify the image is now correctly loaded into the buffer, Get the payload.FirmwareImageAccess.ImageCRC parameter.
Ensure that the data returned is equal to the CRC from Section A.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.FirmwareImageAccess.ImageCRC`
Data Expected with TC	No
TM Details
Data Expected from TC	`ImageCRC` ( + ACK )
Data Size	4 bytes
Data Info	CRC for the data currently being held in the `ImageBuffer`
Allowed Value(s)	00000000 - FFFFFFFF (hex)
Expected Value(s)	Image CRC from Section A

D. Reprogramming the CPLD

D.1.

Get the payload.GMOD.LineNoLastProgrammed parameter.
Ensure that 0 is returned.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.LineNoLastProgrammed`
Data Expected with TC	No
TM Details
Data Expected from TC	`LineNoLastProgrammed` ( + ACK)
Data Size	2 bytes
Data Info	Line number last programmed from the OBC to the MSP/CPLD
Allowed Value(s)	0000 - FFFF (hex)
Expected Value(s)	0

D.2.

Get the payload.GMOD.CPLDReprogrammeStatus parameter.
Ensure that 3 (i.e. its initialisation value) is returned, indicating that the CPLD reprogramming process on the MSP is not currently on-going.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.CPLDReprogrammeStatus`
Data Expected with TC	No
TM Details
Data Expected from TC	`CPLDReprogrammeStatus` ( + ACK )
Data Size	2 bytes
Data Info	Status of CPLD reprogramming
Allowed Value(s)	See table below
Expected Value(s)	03

Where…

`CPLDReprogrammeStatus`	Status
00	In progress
01	Success
02	Fail
03	Init

D.3.

Invoke the payload.GMOD.CPLDReprogramme action to start the reprogramming process.

TC Details
MCS Operation	`Invoke`
Action/Param Name	`payload.GMOD.CPLDReprogramme`
Data Expected with TC	No
TM Details
Data Expected from TC	No ( + ACK )

D.4.

Get , and continue to get, the payload.GMOD.CPLDReprogrammeStatus parameter until 1 (i.e. its success value) is returned.

Tip

If 0 is returned, the CPLD reprogramming is still in progress.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.CPLDReprogrammeStatus`
Data Expected with TC	No
TM Details
Data Expected from TC	`CPLDReprogrammeStatus` ( + ACK )
Data Size	2 bytes
Data Info	Status of CPLD reprogramming
Allowed Value(s)	See table above (i.e. in Step D.2)
Expected Value(s)	01

D.5.

Get the payload.GMOD.LineNoLastProgrammed parameter.
Ensure the returned TM = the size of the image in rows (determined in Section A).

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.LineNoLastProgrammed`
Data Expected with TC	No
TM Details
Data Expected from TC	`LineNoLastProgrammed` ( + ACK )
Data Size	2 bytes
Data Info	Line number last programmed from the OBC to the MSP/CPLD
Allowed Value(s)	0000 - FFFF (hex)
Expected Value(s)	The size of the image in rows from Section A

E. Post-Programming

E.1.

In preparation for the next reprogramming, Set the payload.GMOD.LineNoLastProgrammed parameter to 0.

TC Details
MCS Operation	`Set`
Action/Param Name	`payload.GMOD.LineNoLastProgrammed`
Action/Param ID	1222
Data Expected with TC	Yes
Data Size	2 bytes
Data Info	Line number last programmed from the OBC to the MSP/CPLD
Allowed Value(s)	0000 - FFFF (hex)
Expected Value(s)	0
TM Details
Data Expected from TC	No ( + ACK )

E.2.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

E.3.

Get the payload.GMOD.GMODMode parameter to assess which mode the firmware running on the MSP is operating in.

TC Details
MCS Operation	`Get`
Action/Param Name	`payload.GMOD.GMODMode`
Data Expected with TC	No
TM Details
Data Expected from TC	`GMODMode` ( + ACK )
Data Size	1 byte
Data Info	Payload operational mode
Allowed Value(s)	See table below

Where…

Firmware	`Mode`	Mode
GMOD	1	Idle
GMOD	2	Experiment
GMOD	3	CPLD
GMOD	4	Safe

E.4.

If the payload.GMOD.GMODMode parameter indicates that Idle Mode is on-going, this procedure is now complete.
Else, now Set the GMODMode parameter to 1/Idle Mode.

TC Details
MCS Operation	`Set`
Action/Param Name	`payload.GMOD.GMODMode`
Data Expected with TC	Yes
Data Size	1 byte
Data Info	The mode to set EMOD to
Allowed Value(s)	0-1
Expected Value(s)	1
TM Details
Data Expected from TC	No ( + ACK )

E.5.

Confirm the Set in the previous step with a Get (i.e. confirm the value was set successfully).

Tip

It may take the payload MSP ~tens of seconds to complete the mode change.

END OF PROCEDURE