Housekeeping

Housekeeping Behavior

The housekeeping system collects data from all subsystems periodically and stores the data in files, which are kept on board the satellite. When the maximum number of files has been created, the housekeeping service begins overwriting the oldest files with new data in a circular fashion. The maximum number of files that will be stored can be queried and modified with the GET_MAX_FILES and SET_MAX_FILES commands respectively. These files are persistent and the service will not be adversely affected by power loss. The only concern of power loss is that the time between the last file stored before power loss, and the first file stored after power is recovered may have an unusually long or short time difference.

Housekeeping Commands

All commands are prefixed with obc.housekeeping.

get_max_files

This command is used to view the maximum number of files that will be stored on the satellite before overwriting occurs.

Parameters

[none]

Returns

• err: 0 means no error, anything else means an error has occurred
• max: a 16-bit unsigned integer corresponding to the maximum number of files that will be stored

set_max_files

This command is used to set the maximum number of files that will be stored on the satellite before overwriting occurs. Attention: if this new number is lower than the existing number used on the satellite, all housekeeping files will be destroyed and the service will start over completely. This is done to ensure service integrity and prevent undefined behaviour. Increasing the maximum number of files will have no new effects on the existing files.

Parameters

• new_max_files: an unsigned 16-bit integer that will be used to set the maximum number of housekeeping files stored on the satellite before overwriting occurs

Returns

• err: 0 implies that the number was correctly set (nevertheless it is recommended to confirm the new number using get_max_files)

get_hk

This command is used to retrieve housekeeping files from the satellite. Files can be queried by multiple means using this command. The command allows querying by timestamp or by file ID. If neither a timestamp nor a file ID is known, or the user wants the most recently acquired file, they can simply supply the values of 0 for the timestamp and file ID. This will tell the program that these parameters should be ignored. If both parameters are non-zero, then the timestamp will be used, and the file ID will be ignored.

Parameters

• limit: an unsigned 16-bit number corresponding to the maximum number of files to return (each file is sent as an individual CSP transmission and all files are sent over the same single connection, thus the number of files returned will be in the range [0, limit])
• before_id: an unsigned 16-bit parameter used to specify collecting a specific file from the filesystem

This command would generally NOT be used blindly by a human user and is instead intended for use by an automated system. The number given as a parameter will be the dataPosition field of the oldest file that has already been received by the user. Numbers larger than that set by set_max_files will be rounded down. Example: user receives 2 files. These are files 34 and 35. Where 34 is the older file. When the user places a request where before_id = 34, they will receive file 33. Note: if the number of files requested is greater than the ID of the newest file, then the oldest files will have an ID number greater than that of the newest file. E.g. if the user requests 7 files starting at file ID 5 they will receive the files: 5, 4, 3, 2, 1, 20160, 20159.

• before_time: an unsigned 32-bit integer used to specify collecting a file from the housekeeping service that corresponds to a specific point in time, as denoted by a UNIX timestamp

Note: Tue Jul 27 2021 19:55:49 GMT-0600 (Mountain Daylight Time) corresponds to a UNIX timestamp of 1627437349 and all times specified are required to use this single integer notation. The value given as a parameter will be one of two things. The time can be either a specific point in time from which the user wants the files from immediately before that time, or it can be the time specified in the UNIXtimestamp field of the oldest file that has already been received by the user which is similar to the functionality of the parameter above.

Returns

• err: 0 means no error, anything else means an error has occurred
• final: a piece of metadata used by the ground station to tell if another packet is coming on this single connection (1 means more data coming, 0 means this is the last packet)
• UNIXtimestamp: the timestamp of when the file was created and stored
• dataPosition: the number that the created file is stored at
• ... along with additional data - see each sub service documentation to learn more

Sample Usage

The following are a few sample use cases with explanations.

• obc.housekeeping.get_hk(1,0,0): this command will get one file and the file will be the most recent one collected by the system
• obc.housekeeping.get_hk(10,150,0): this command will get 10 files working backwards from file number 149, and they will be received as 149,148,147,146,145,144,143,142,141,140 in that order
• obc.housekeeping.get_hk(5,0,1627437349): this command will get 5 files working backwards from the unix time 1627437349, if no files are available in relation to this timestamp then the 5 most recently acquired files will be sent instead

Additional Information

This section is meant for debugging, understanding, and corruption handling of the housekeeping service. The true implementation is not such as described, but is instead done in a way to improve read/write speed and timestamp search time.

Housekeeping data is stored in one large file with the path: VOL0:/tempHKdata.TMP. This file holds each set of data end to end in binary format. The storage and acquisition of the data is performed by opening the file and performing an fseek command that moves based on the size of the data structure and its index in the file. It is important to know that the files are not 0 indexed. They are 1 indexed, but they are shifted to avoiding wasting space at the start of the file. Also, if the size of each housekeeping dataset changes, then the entire file needs to be deleted and remade as it will be corrupted.

The sets of data can be queried based on their index number directly or they can be queried by their timestamps. In order to be queried by timestamp, the timestamp of each set is stored in a dynamically allocated array. This array is kept in a file called VOL0:/HKconfig.TMP. With each new dataset, the single value in the file at that index is updated with the timestamp of the data. In the event of a power reset, the data is loaded from the file. When a request is made for a file, based on timestamp, a binary search algorithm is used to rapidly search the array of timestamps which is inherently sorted. A few other values are also stored in this particular file and include the maximum number of files, and the last file written. This prevents data loss by power reset.

The next important thing to note is what to do in the event of an unrecoverable file corruption that causes problems with the data. In this situation an operator should delete all data pertaining to the housekeeping service. This can be done by using the set_max_files command to set a number that is lower than the existing value. By doing this, all files will be deleted or rewritten, and the service will start over. After this is done, the operator can use the same command to restore the desired number of datasets to store.