TITAN

This is the flight computer for the Domecracker liquid bi-propellant rocket. It's build with the following hardware in mind.

Descriptions	Part Number	Protocol Used	Instance	Documentation
MCU	STM32H745XIH3	X	X	datasheet manual
IMU	ICM-42688-P	SPI	2	datasheet
Magnetometer	MMC5883MA	SPI	2	datasheet
Barometer	MS561101BA03-50	SPI	2	datasheet
Temperature Sensor	TMP125AIDBVR	SPI	2	datasheet
Radio	SI4467-A2A-IMR	SPI	3	datasheet
GNSS	NEO-M8Q-01A	SPI	2	datasheet
RS485 Transciever	THVD2442DRCR	UART	2	datasheet
ADC	ADS124S08	SPI	1	datasheet
Current Sensor	INA223AIDGSR	I2C	1	datasheet
Actuator Drivers	MAX22217	SPI	4	datasheet
CAN	TCAN3414	UART	1	datasheet

Overview

This flight computer's primary two functions are to transmit sensor data back to ground, and self-correct it's trajectory. It achieves this through the following structure:

Within the modules, the periphs, devices and apps form a stack which supports each other to finally provide the apps to the main system code. The kernel, util, and internal modules supports the entire stack. The blue arrows demonstrates one potential dependency chain between different module APIs. In this case the dma API from the util module is being used by the uart API implementation, which is used in the rs485 implementation, which is then used in the start-sequence implementation. The green arrows show dependencies between modules as a whole, where apps is dependent on devices is dependent on periphs, and all three are dependent on kernel, util, and internal.

Structure

Overview

The project has the following structure:

• apps/: application code
• dev/: development utilities
• modules/: groups of APIs used by the main system.
• tests/: tests for code

Modules

Modules are groups of APIs that are similar in function and level of abstraction and that are also independent of each other, although they may use APIs from other modules. Here is the module tree with all APIs we expect to have on the finalized project:

• pheriphs: mcu peripherals.
  • spi: high-speed syncronous communication protocol.
  • i2c: low-speed asyncronous commuication protocol (less pins).
  • uart: simple asyncronous communication protocol.
• devices: device drivers.
  • imu: internal measurement unit. roll pitch yawn..
  • temperature sensor
  • barometer: measures atmospheric pressure.
  • gnss: GPS. x, y, z, speed, ground speed.
  • radio: for telemetery.
  • magnetometer: magnetic information. like a compass.
  • rs485: ground communication while on land.
  • ADC: analog to digitalc converters.
• apps: applications.
  • data-telemetry: telemetry system.
  • flight-control-system: system that self-corrects trajectory.
  • start-sequence: how the rocket starts.
• kernel: kernel code.
  • thread: concurrent execution.
  • mutex: sharing state between threads.
  • semaphore: signaling events to threads.
  • sys: architecture level system utilities.
  • time: system time utilities (sleep).
  • crit-lock: interrupt-safe lock.
  • host: semi-hosting facilities (debugging).
  • flag: cross-thread communication method.
  • alloc (maybe): memory allocation.
  • future (maybe): access result of async operation.
• util: utilities.
  • core: extentions to language capabilities.
  • debug: debug utilites. (assert, breakpoint)
  • errc: error utilities.
  • macro: utilities for writing macros.
  • math: math utilities.
  • atomic: atomic operations.
• internal: abstract mcu dev tools
  • dma: direct memory access
  • exti: external interrupts
  • mmio: memory mapped input output
  • interrupt: interrupt reference information

Contributing

Quickstart

Filter the issues list by issues labeled "master issue". Browse until you find a leaf issue (issue with no children) that you would like to work on. Complete the issue's task in a branch who's name is the issue's path followed by the leaf-issue's number, seperated by hyphens. Example: apps/bug-radio-not-initialized-73.

Once finished, create a pull request into the main branch of the parent issue of the issue you worked on. The name of this branch will be the parent issue's path followed by /main. Example: apps/main. This pull request will be reviewed by those assigned to the parent issue, and if accepted, merged into to the parent issue's main branch. The code will trickle through the branching system through pull requests done by higher level management, and eventually reach main if it passes the testing process.

Congrats! You have made your first contribution.

Contributing Guide

This is a wholistic guide as to how our contribution system works.

Issues

The issues list contains the following master issues:

• documentation: contains the development of documentation.
• apps: contains development of application level code.
• dev: contains all development/devops tools.
• tests: contains tests.
• modules: contains APIs used by main application.

All other issues should be descendants of these master issues. These sub-issues should be labeled either feature or bug, and their name should be a short (about 5 words or less) description of the issue prefixed by bug or feat depending on its label. Name should be all lowercase and space seperated. Example: feat semaphore initial draft.

The hierarchy of the modules master issue should always reflect the module tree. It should contain sub-issues for each module, and then within the issues for each module, it should contain an issue for each individual API within the module. These issues are called module API issues, and are important for branching. New sub-issues should be created within the module API issues.

Here is the complete issues tree:

In red are the master issues, in blue are the modules, and in green are the module API. Sub-issues are created at the leaves of the hierarchy, ie. at the non-"modules" master issues and at the module API issues. If you feel that a master issue, module, or module-API is missing, please report it to management.

Branching

All master issues except modules, as well as module-API issues, have a corresponding branch group. This is a group of three kinds of branches:

• The main branch: mandatory & unitary for all branch groups. Contains the latest state of the system described by the corresponding issue. Naming scheme is <issue-path>/main. Examples: tests/main, modules/kernel/semaphores/main.
• Bug branches: branches which correspond to a bug-labeled issue within the issue system. All work for that bug should be done within this branch and merged back into the issue's main branch. Naming scheme is <issue-path><issue-number>, where everything is hyphen seperated. Example: modules/kernel/feat-semaphore-initial-draft-98.
• Feat branches: Same as bug branches but for features.

Once the main branch of a branch group is ready to be tested, it is merged into untested along with the tests, tested, and merged into main if testing is successful.

Here's an illustration of what this looks like:

Shown in blue, is the abstraction of how individual branch groups all merge into untested. The actual mechanism behind this is shown in green, where the main branch is worked on through bug and feat branches before being merged into untested.

For convenience, we refer to issues w/ a branch group, that is all master issues except "modules", and all module API issues, as working issues, since they are the only ones where coding should be done. All other issues (ie. "modules" and module issues) are structural and used to organize module-APIs hierarchically.

Responsibility

Some (or all) engineers will be assigned a module-API which they will be responsible for. They will be the project overseer or just overseer for said api. This entails the responsibility of reviewing all pull requests into the main branch of the working issue, and for creating pull requests to untested when appropriate.

To help with accountability and ensuring code quality standards, the overseer must complete the following checklist:

• Is the API fully documented?
• If there is an implemention, is the implementation fully documented?
• Does the code seem correct and does it suit our purposes?
• Does the code adhere to the style guide?

The overseer should address each of these points in at least one sentence when reviewing the pull request.

The RE will be responsible for pull requests going into untested, the testing process, and the merge into main. He will follow the following checklist:

• Does the new code fit into the existing system?
• Are there tests for the code? Are the tests robust enough?
• Does the code adhere to the style guide?

These checklists should prevent people from being able to cut corners during review. it helps to hold people accountable for the decision making process behind their review.

Conclusion

The workflow should be to choose or potentially create a sub-issue within a working issue and to find or create a branch for it which follows the naming scheme. Complete the issue within this branch, and create a pull request from this branch into the main branch of the branch group, tied to the issue you worked on.

This system is more complex than a simple main dev bug feat system, but its modularity and defined structure provides great collaboration advantages:

1. Isolated environments for subsystem development.

   Through the use of branch groups, this system isolates the various subsystems of the project to a very high degree. It also ensures that the latest state of any one subsystem is in an accessible place.

   These two features make it easy for subsystems to collaborate without getting in each other's way, and for dependent subsystems to easily get the latest header files from another subsystem.

   Another benefit is that a dependent can easily submit an issue if the API of a dependency does not meet the required functionality; overseers only have to check one place for all issues in their system.

2. Series of checks before reaching main.

   This system provides two checks before reaching main: the overseer must first approve the issue's merge request into the working issue's main branch. The RE must then appove the overseer's request into untested.

   This, alongside the testing phase, means we have a high level of accountability for which code is actually finished. And, it is much more difficult for low-quality code to pervade the codebase. Low quality contributions should be contained to the leaves of the branching hierarchy.

3. Project tracking parallels branching.

   The issues tree tells you which branch you should code in and merge into when working on an issue. Without this, it would be confusing what is being worked on where. The fact that each leaf issue corresponds to a branch with a parent branch that should be merged to, makes the corresponding branching strategy and resulting pull request intuitive, allowing for seamless syncronization between branching and the issues list.

This system is robust, scalable, and handles dependencies well. If we use it effectively, it can take us to FAR-OUT and support us well into the future.

Style Guide

Formatting

• Use 2 space indents.
• Use K&R style brackets.
• Wrap lines that are greater than 100 characters.

Naming

• All identifiers (types, functions, variables, etc) must be camel_case.
• Types must be denoted with a trailing '_t'.
• All publically exposed identifiers must be prefixed with 'ti_'.
• Identifiers of global constants (including macros) must be ALL_CAPS.
• All private/internal global variables, functions and types must be denoted with a preceding underscore.

Code Constructs

• Do not use typedefs.,
• Only use macros if necessary (prefer functions always).
• Avoid using 'magic numbers' in your code.
• Return an error code (ti_errc_t).
• Use ASSERT() only for testing.