-
Notifications
You must be signed in to change notification settings - Fork 3
ORCA2Sat Requirements
This document outlines the design and implementation requirements of the OBC for ORCA2Sat.
Each requirement has an ID for tracking. Requirements are referred to as DRs, meaning "design requirements." Requirements can reference other requirements for clarity, but should stand on their own. Requirements should follow the EARS syntax, which basically just means that they are concise, clear, and encapsulate only the required information to determine their scope.
To add an unknown item, please tag it as todo: and wrap with [ ].
Conditions or signals can be defined as all caps such as OFF_STATE and can be used in requirements. They must have a DR that defines them.
Headings for requirements sections are H3, which use a ### prefix.
Design requirement IDs are H4, #### prefix.
Constraints are the real-world limitations that must be met by the OBC. These also include limitations that other subsystems must cooperate within.
These constraints may be imposed by other aspects of the satellite, or they may be derived from OBC detailed design requirements since an existing design is being leveraged for this OBC.
The OBC shall operate on 0.4W or less in active mode.
Voltage range: 3.2-3.5V
The timestamp resolution shall be 1 second
All subsystems shall provide minimum 1 unit of prototype hardware for exclusive use by the OBC team, per hardware iteration
- This hardware shall be as functional as possible (given that it’s a prototype)
All subsystems shall provide an interfacing document that meets the computing team’s requirements as soon as possible (minimum 1 month before first hardware)
All subsystems shall dedicate 1 liaison to work with the OBC team. This person shall be involved in subsystem design and design of the interfacing software.
Communication with the payload will happen over an SPI interface
Maximum data rate into OBC: 400 bytes/second for 2 seconds during STATE_READY
- Signal level: 3.3V
- Chip selects: 4
- Dual or quad MISO mode: yes
The OBC may disregard data from the payload if the data link or buffers become saturated. This will be logged on the OBC, but not communicated to the payload.
During activation of any payload, not all standard telemetry items can be expected to be logged
[todo: Depends on payload data requirements. May need to suspend everything if payload needs all of the resources available]
The OBC may decide to stop or deschedule execution of a payload sequence based on power requirements or entry into STATE_SAFE
Payload activities must be planned to account for 3 second worst case absolute epoch execution time tolerance
- This is due to the soft real time nature of the RTOS and the RTC’s 1-second resolution
During activation of the payload, no commands from the ground may be acknowledged
All subsystems shall make every interface pin (I2C, SPI, GPIO) known to the OBC team before the bus layout is finalized.
- This shall include special requirements (interrupt capability, reset line, etc.)
The OBC shall be the master on all communication interfaces (SPI, I2C,UART)
Pre-defined interrupt lines may be used as a doorbell for the OBC to initiate communications (example: RF RX interrupt)
All devices on the I2C bus chain shall provide a dedicated reset line to the OBC sufficient to reset their I2C hardware in the case of a bus lockup (likely a hard power reset)
All devices on the I2C bus shall support a 100 KHz-400 KHz clock speed.
All I2C devices on the satellite shall support the same clock speed (at the same time) without reconfiguration.
All devices on the I2C bus shall have a unique 7-bit address
Two identical commands cannot be scheduled to run at the same time.
Immediate commands are executed as soon as practical after they are received
Until the RTC backup power source is fully charged, a consistently-incrementing epoch is not guaranteed.
- This may manifest itself in strange telemetry timestamps and command execution
Log files must be downlinked at least every 7 days to avoid data loss.
System-level requirements are intended to guide the design of other subsystems and to provide a high-level overview of the capabilities of the OBC.
The OBC will beacon standard telemetry 5 times every x minutes in STATE_READY.
- This is the default, but the delay and repeat are configurable on-orbit
A delay of 0.5 seconds will be inserted after every telemetry set downlink to allow for commands to be uplinked.
OBC will delete the oldest set of time tagged telemetry every 7 days, or when the filesystem becomes full (whichever comes first)
- Deleted data is irrecoverable
OBC shall be able to store 30 time-tagged commands to schedule activities in the future.
If two commands receive the same time tag for execution, the command received first will execute first. This may or may not delay the execution of the second command.
Access to the OBC debug connectors (mini or micro USB and JTAG) from outside the satellite is strongly preferred
The OBC epoch will be started at first successful power-on of the satellite.
No radio transmissions will occur until 30 minutes of epoch time have elapsed.
Activation of any payload must be planned in advance and uplinked to the OBC to be executed at an absolute epoch.
There must be a minimum 30 second delay between scheduling and execution of a payload command.
Scheduled activities will occur at the scheduled time with a tolerance of of no worse than 3 seconds absolute epoch
- assuming correct satellite operational state & available power
The OBC shall immediately acknowledge any uplinked command with a message indicating whether the command is valid or not.
To maintain STATE_READY, a command must be issued to pet the watchdogs at minimum every 48 hours
STATE_SAFE is the startup mode of the satellite and will be entered if a watchdog pet command is not received every 48 hours
The OBC can exit STATE_SAFE into STATE_LOW_POWER on its own and maintain STATE_LOW_POWER until battery charge is sufficient for operation in STATE_SAFE.
Entry into STATE_READY from STATE_SAFE shall happen via a command from the ground.
After the first 24 hours operation with the power system at a level sufficient to charge the RTC backup power source, the power source shall be sufficiently charged to provide 7 days of RTC operation.
Upon request, the power system shall return data about the battery state of charge for the OBC
- This data shall be sufficient for the OBC to calculate whether a particular operation (ex: payload execution) will place the power system at a dangerously low level
[Removed]
All I2C-based devices shall provide two 0603 footprints for I2C pullup resistors on the SDA and SCL lines.
- The footprints shall be located very close to the chip.
- These will normally be unpopulated
The OBC shall downlink data packets in a known format
These requirements are intended to drive the design and implementation effort. They describe the design to a very precise degree.
The OBC will have enough nonvolatile storage to save 7 days of telemetry logs and flags with 40 % over provisioning.
The OBC will have a realtime clock with 1 second resolution.
The RTC will start counting at 0 upon the first system power-on (shortly after deployment from the p-pod).
The RTC shall be provided with a backup power source good for at least 7 days of backup power at the beginning of the mission.
[removed]
The RTC shall communicate with the OBC over an SPI interface.
The RTC shall have a customizable alarm with an ALERT pin that will go HIGH when the alarm triggers. The OBC will configure the alarm to generate the ALERT signal at some point (defined in seconds) in the future. The OBC can also cancel an alarm.
After 24 hours of nominal power to the OBC system, the RTC backup circuit shall have stored sufficient power to operate the RTC for 7 days.
The OBC shall conform to the UVIC backplane standard and will be a single blade.
The OBC shall have a header with a way to disable/reset all onboard auxiliary hardware. This will be used to test failure modes.
- RTC
- Flash
- Temperature sensor
The OBC shall have a pin to hard-reset any device that communicates using I2C over the bus connector.
This may be a reset pin on the device, or a hard power cylce. Whichever method is used, it shall be sufficient to reset the device's I2C hardware to fix bus lockups.
The MCU used shall have a launchpad development board.
TMS570LS1224
The OBC maintains a state machine with 4 states:
- STATE_SAFE: a well-defined mode where we're logging telemetry but not executing scheduled commands
- STATE_READY: normal mode, OBC can execute time-tagged commands and switch to payload execution
- STATE_PAYLOAD: only executing the payload. This state is only active for brief periods of time when the payload is executing during a pass.
- STATE_LOW_POWER: extended deep sleep to significantly reduce OBC power draw.
The state handler will be implemented as an RTOS task with moderately high priority. The state handler task will execute state transitions, and is triggered upon receiving a notification from any other part of the system that a transition should occur.
To switch state, any other task will send a state transition message to the state handler task via a FreeRTOS direct-to-task notification.
State transition messages will have a 8-bit identifier with the following format:
[7] - if 1: state transition is enabled, if 0: state transition is disabled. Defaults to 1. [6:0] - transition message unique ID. Unique ID per transition source.
Only the lowest 7 bits will be sent to the state handler by tasks. The 8th bit will be stored with the ID in the state transition message table. By indexing this table with the state message ID, the enable/disable bit can be looked up by the state handler.
State transition messages will be sent directly to the state handler task for it to execute the state transitions. State transition messages will be logged unless they are [todo: don't try to log transition messages that result from filesystem problems]
The state handler task will switch on the transition message and if appropriate, execute the state switch. If the transition message would result in a switch to the current state (such as OBC temperature transition while we're already in STATE_SAFE), simply log the message.
[todo: fill out the table] State transition message IDs: 0x01 - OBC temperature too low [READY - SAFE] 0x02 - OBC temperature too high [READY- SAFE] 0x03 - STATE_LOW_POWER exit [LOW_POWER - SAFE] 0x04 - RTC_ERROR condition [ANY - SAFE] 0x05 - FS_ERROR condition [ANY - SAFE] 0x06 - Command transition [SAFE - READY]
It shall be possible for state transition messages to be disabled via a command. This is to prevent infinite loops of automatic entry into a state.
Upon receiving a state transition message, the state handler task shall check that the message is not disabled message[7] = 0 = disabled. If the message is disabled, no state switch will occur.
The state transition source table shall be backed up in nonvolatile memory and periodically checked/refreshed with the one in RAM. State transitions shall use the copy in RAM.
[todo: reconcile with transition table that's there currently]
A state transition will include:
- suspending tasks that are not required in the state
- logging the state entry time and transition flag
Upon receiving a transition message but before the state transition (the process of validating the transition message and suspending tasks), the state handler task shall take the following mutexes:
- filesystem SPI mutex
- i2c mutex
- RTC mutex
This will ensure that no tasks can take hold of the hardware just before they are suspended. It will also ensure the system is essentially idle before executing a state transition.
Once the transition is complete (the requisite tasks are suspended), the state handler task shall turn back the mutexes to control by the rest of the system.
This is the STATE_SAFE condition. The following conditions will trigger entry into SAFE mode:
- A WD_RESET
- RTC time not incrementing
- More than 5 filesystem errors
- No command received in 2 days
- Hard power cycle of OBC
- Exit STATE_LOW_POWER
[Removed]
In STATE_SAFE, the following tasks will run:
- BMS checker
- temperature logger
- [todo: others]
- BEACON_TX
In STATE_SAFE, the following tasks will be suspended:
- payload operations
- time-scheduled commands
In STATE_SAFE, the BEACON_TX task shall be executed. BEACON_TX will do the following:
- if power level permits, send out a standard telemetry packet 10 times with 5 seconds between packets, once every 5 minutes [todo: determine actual times].
STATE_SAFE can be exited into:
- STATE_READY by a command from the ground
- STATE_LOW_POWER upon battery SoC dropping below [todo: level]
This is the STATE_LOW_POWER condition. The following conditions will trigger entry into this state:
- battery SoC below 30 % [todo: percentage]
- command from the ground
The epoch scheduled by a payload command is the time the payload will start executing. Setup before payload execution will be handled by the OBC.
Entry into STATE_PAYLOAD will be automatically scheduled to happen by the OBC 30 seconds before the desired payload execution time.
Before entry into STATE_PAYLOAD, the state handler shall suspend the following tasks:
- [todo: which tasks to suspend?]
[todo: state payload diagram]
Upon entry into STATE_PAYLOAD, the OBC shall begin polling the RTC. When the epoch reaches the scheduled value for the payload, the OBC shall stop polling and execute the command.
A payload command from the ground shall have the following information:
- payload execution start epoch
- payload execution time (seconds)
- payload flag (CHIME/LASER)
Upon receipt, the OBC will schedule a payload command modified to execute 30 seconds prior to the requested execution time.
- the time difference will account for any delays involved in suspending tasks for entry to STATE_PAYLOAD
The command's argument field will provide the execution and start time required for the payload command.
The start epoch, exec time and flag global variables will be set to the command arguments when the payload command is executed by the scheduler, before the transition to STATE_PAYLOAD is requested.
- this provides the ability for multiple payload commands to be scheduled, as their information is held in the command schedule queue
The OBC shall have a LOW_POWER state that suspends all substantial activity [todo: define this better] and places the MCU in a low power state with wakeup conditions that are consistent with OBC.LP.2.
Note: this will probably use tickless idle
The LOW_POWER state can be exited on the following conditions if the battery charge level is safe to operate:
- RTC ALERT
- Message received over the radio
In all cases, the OBC will exit STATE_LOW_POWER into STATE_SAFE.
The OBC shall utilize the FreeRTOS idle task hook to place itself in a lower power mode as frequently as possible.
The LOW_POWER state will have a configurable sleep time. By default, the sleep time is 10 minutes.
Upon entering STATE_LOW_POWER,
- The RTC alarm will be set to the sleep time in OBC.DR.LP.4
- Sleep mode will be entered
If upon wakeup from conditions in OBC.DR.LP.2 the power level is not sufficient to continue operations, the steps in OBC.DR.LP.5 will be executed again after logging 1 set of standard telemetry.
If the power level is sufficient, OBC.DR.LP.2 shall apply.
The OBC shall run FreeRTOS version 10. Unless a critical bug fix comes out, the version will not be upgraded during the life of the project.
A task with maximum priority will be created to pet the external watchdog. It will be configured to run 2x as fast as the watchdog expires. This task can be suspended in an operation known as a WD_RESET.
This is the RTC_ERROR condition.
If the RTC ceases to function, a 1 second timer shall be started and used to increment the epoch. This will be driven by a state machine in the RTC driver. The 1 second timer will be used to increment the onboard epoch instead of the hardware RTC until the RTC_ERROR condition is cleared from the ground.
STATE_SAFE will be entered.
Interface drivers (CAN, SPI, I2C) shall be designed not to lock up. They must all have timeouts and report error codes if timeouts fail. All internal error registers will be checked in the driver functions.
All interface drivers will be protected from multiple accesses by a FreeRTOS mutex.
If upstream functions receive an error code from a driver, they must be able to continue operation. They shall log the error code and revert to default values.
If 5 or more consecutive I2C errors are reported by the low level drivers, the I2C state machine shall set the I2C_ERROR stdtelem_error_code.
DMA shall be used on the debug UART.
Upon power-on or reset, the OBC shall log the reason for reset (RFR) in the system log. The internal registers can distinguish between hard/soft/debug resets.
All components covered by a stdtelem_error_code (OBC.DR.TELEM.2) shall implement an internal state machine that will ensure lockups do not occur during error conditions.
The logic shall directly use the stdtelem_error_code bits so that they don't need to be synced between software components.
A general-purpose error logger shall be provided. This error logger will write to an error log file.
These calls can be inserted throughout the software stack. Each has a unique error code.
Note: the interval for these items should be the same so they can nicely go into one task.
A check every [todo: interval] will ensure that the RTC time is incrementing. If RTC is not incrementing, STATE_SAFE will be invoked and RTC_ERROR will be invoked.
This check will happen in STATE_SAFE and STATE_READY and will execute in a medium priority task.
Flag file entries will be checked for consistency against the OBC's onboard flag struct. If they are not the same, the mismatch shall be logged as an error and STATE_SAFE entered if state is STATE_READY. This check will occur at [todo: interval].
In this case, the flag copy on the OBC (not the flash) will be used.
The OBC shall implement a file system for access to nonvolatile storage. The filesystem will allow creation, deletion and retrieval of files.
Two categories of files will be used. Log files will contain timestamped data. Flag files will be persistent and will contain backups of system configuration parameters.
All entries to log files will be automatically timestamped with the mission epoch at time of write.
An estimate of space remaining on the file system will be available by command.
A new set of log files will be created every 24 hours.
If there is insufficient space on the filesystem to support a write, the oldest set of log files will be deleted and a message logged.
The filesystem shall have a convenient, printf-style API for writing to telemetry log files.
The chosen filesystem library shall provide error checks and codes.
If a filesystem operation does not succeed, it shall not be reattempted. An error will be logged. A filesystem clean operation will be executed. A detected failure of a filesystem clean will not trigger another filesystem clean operation (this prevents loops).
The number of failed filesystem operations will be logged. If it reaches 5 since last hard reset, an attempt will be made to log the error. Then STATE_SAFE will be entered. The stdtelem error code will be set to FS_ERROR.
If FS_CRITICAL_ERR is invoked, no attempts by the onboard software to read/write to flash shall actually execute a write. This ensures that flash will not hang the system.
A state machine within the flash code can be used to control this access.
There shall be a command to directly write invalid values into flash so as to corrupt the file system. In this case, smooth recovery is expected.
The OBC telemetry packet will consist of the following fields:
- stdtelem_error_code
- current epoch
- filesystem usage
- current state
- [todo: add other things]
The stdtelem_error_code is a set of bits that are kept in context without nonvolatile memory, with the idea being that bits can be set even if external flash is not working.
A bit being set means the error has been reported by the state machine for the component.
The bits and their meaning are defined below:
RTC_ERROR - 0x00 FS_ERROR - 0x01 I2C_ERROR- 0x02
Upon receiving any command from the ground, a software timer shall be reset. The timer shall have an expiry period of 2 days. If the timer expires, STATE_SAFE will be entered.
WIPE_AND_RESET command shall completely erase all nonvolatile memory and then issue a WD_RESET to promote re-generation of flag files.
The ability for the any of the stdtelem_error_code_bits to be cleared from the ground will be present.
A command shall be provided to read the current RTC epoch, regardless of RTC_ERROR status.
It would read the built-in timer value if the hardware RTC has failed.
This is a placeholder for operational requirements.
Upon detecting FS_CRITICAL_ERR stdtelem_error_code, the ground crew will issue WIPE_AND_RESET command to the satellite after attempting to downlink data.