Documentation by MuhammadAli8209 · Pull Request #222 · ISSUIUC/MIDAS-Software

MuhammadAli8209 · 2026-08-08T21:14:54Z

Documentation for the MIDAS folder

telemetry comments added

shell folder

hardware docs

logging docs

Adding comments to flight systems docs

github-actions · 2026-08-08T21:15:46Z

FSM SILSIM: 6/6 passed ✓ — plots

mpkarpov-ui

Thanks you guys for taking on this effort! I think it's been a while since we've had a documentation pass over the system.

That being said, I think there's some work to be done on keeping comments terse-- Code should be self-documenting. I also noticed a few things that confused me so I'm adding some comments to the review.

mpkarpov-ui · 2026-08-09T16:48:23Z

+    // Check minimum horizontal velocity if enabled.
    if (vx_min != -1 && cur_vx < vx_min) { return false; }
+
+    // Check maximum horizontal velocity if enabled.


vx refers to the x-coordinate in GNC space which is actually vertical velocity

mpkarpov-ui · 2026-08-09T16:51:47Z

+    /// Minimum allowable horizontal velocity.
    float vx_min;
+
+    /// Maximum allowable horizontal velocity.
    float vx_max;


see above, vx = vertical velocity

mpkarpov-ui · 2026-08-09T16:52:00Z

+     * @param cur_tilt Current vehicle tilt.
+     * @param cur_motor Current motor count or stage.
+     * @param cur_time_since_launch Time since launch in seconds.
+     * @param cur_vx Current horizontal velocity.


mpkarpov-ui · 2026-08-09T17:39:39Z

-// any number of leading slashes is tolerated.
+/**
+ * @brief Helper evaluation block verifying if a given directory file targets the live logging output metrics stream.
+ * @param arg Active flight vehicle operational class instances.


what is this comment??

mpkarpov-ui · 2026-08-09T17:39:57Z

+/**
+ * @brief Safety sweep utility targeting deletion tasks spanning passive log file fragments across media partitions.
+ * @details Retains and isolates the currently running data structure files to guard active recording sessions.
+ * @param arg Hardware telemetry core coordination state machine structures.
+ * @return true On clean execution sweeps; false if hardware blockades disrupt operations.
+ */


Genuinely what are these comments

mpkarpov-ui · 2026-08-09T17:40:12Z

+ * @brief Packages and streams unified high-fidelity launch session artifacts down telemetry pipelines.
+ * @details Interleaves structure elements, system metadata tracking logs, and direct checksum validation.


????????????

mpkarpov-ui · 2026-08-09T17:40:35Z

please reconsider all of these

mpkarpov-ui · 2026-08-09T17:41:26Z

 void Telemetry::transmit(RocketData& rocket_data, const MIDASEEPROM& eeprom, LEDController& led) {
    // static_assert(sizeof(TelemetryPacket) == 20);

+    // Build the packed structured data frame
    TelemetryPacket packet = makePacket(rocket_data, eeprom);
+    // Provide visual indication of data frame transmission
    led.toggle(LED::BLUE);

+    // Hand over the payload to the specific RF transceiver driver
    backend.send(packet);


these comments seem overly verbose

tjmcmanamen38

Thanks everyone for all the work on this!

I'll largely echo Michael's feedback - just more or less there's some places where comments seem to be trying to describe too much and other places where I think they're trying to oversimplify things a bit much.

Also apologies if I'm mistaken on this but a few of these comments are giving me a bit of an AI vibe which to be completely frank I'm not a huge fan of for Spaceshot work in general and definitely documentation.

Overall a lot of my stuff is just nitpicking lol (as you know I can be quite the nitpicker) so up to you how much you want to change but I would encourage reviewing everything a bit more and making some refinements. And I know Michael and I are always happy to give feedback and please please please reach out to us if you need any help with stuff cause ultimately we're the people most familiar with this codebase and want to make sure that you all understand it too ❤️

tjmcmanamen38 · 2026-08-09T21:12:25Z


+
 bool FSMPyroAction::conditions_met(FSMState fsm_state, float cur_tilt, uint8_t cur_motor, float cur_time_since_launch, float cur_vx) const {
+    // Pyro must be enabled.


imo most comments in this function are fairly unnecessary since the if statements are pretty self explanatory

tjmcmanamen38 · 2026-08-09T21:46:28Z

+
+        /**
+         * ============================================================
+         * SAFE STATE
+         * ============================================================
+         *
+         * The vehicle is fully disarmed. The only permitted transitions
+         * are into PYRO_TEST mode or ARMED mode through explicit commands.
+         */


I appreciate the detail with these but I don't think we need to dedicate so many lines to this, just makes it harder to find the actual code between all the comments so id suggest at minimum removing all the =========. I also think its useful to not remove the detail from the comments in this function about where the commands are coming from (wirelessly in this case)

tjmcmanamen38 · 2026-08-09T21:50:40Z

        case FSMState::STATE_PYRO_TEST:

-            // Force transtion to safe if requested + clear all transition flags.
+            // Immediately return to SAFE if requested.


this is just removing detail imo

tjmcmanamen38 · 2026-08-09T21:51:06Z

        case FSMState::STATE_ARMED:

-            // Force transtion to safe if requested + clear all transition flags.
+            // Allow immediate disarm if commanded.


see previous

tjmcmanamen38 · 2026-08-09T21:51:56Z

-                commands.FSM_should_set_cam_feed_cam1 = true;  // Set camera to side cam
-                cur_state_lockin = false;                      // Reset "state lock in" flag for boost detect
+                launch_time = current_time;                    // Record launch time.
+                time_entered_cur_state = current_time;         // Record BOOST entry time.
+                commands.FSM_should_set_cam_feed_cam1 = true;  // Switch camera feed.


switch camera feed removes detail. what is cam1?

tjmcmanamen38 · 2026-08-10T05:09:52Z

file should be deleted (autogenerated on build)

tjmcmanamen38 · 2026-08-10T05:12:14Z

personally I see EEPROM as very distinct from logging and feels weird to categorize them in the same folder (configuration data vs flight data more or less)

tjmcmanamen38 · 2026-08-10T05:17:45Z

 }

+/**
+ * @brief Router terminal handle processing sub-demands targeted toward flight profiling rules.


sorry this wording just feels really unintuitive

tjmcmanamen38 · 2026-08-10T05:27:23Z

+# Running SILSIM
+
+To build and execute the Software-In-The-Loop simulator:
+
+```bash
+pio run -e mcu_silsim
+```
+
+SILSIM allows flight code to be tested without physical hardware.
+
+> More documentation describing simulation inputs, outputs, and workflows will be added later.


silsim is insanely outdated and does not do anything with the current midas software so I don't think its useful to document how to run it until we having a working version in this repo

MuhammadAli8209 and others added 20 commits June 27, 2026 00:10

put everything in folders

798a3a5

fixes for hilsim

2d0782e

finite-state-machine documentation

6f52b7d

pass fsm sim builds

60d464f

telemetry comments added

b6d7888

Merge pull request #217 from ISSUIUC/telemetry-docs

5810853

telemetry comments added

shell folder

cf68f1e

Merge pull request #218 from ISSUIUC/shell

ca9a619

shell folder

hardware docs

8306b5f

Merge pull request #219 from ISSUIUC/hardware_docs

3469c61

hardware docs

logging docs

a319efe

build fix

3d1c780

Merge pull request #220 from ISSUIUC/logging_docs

def3955

logging docs

adding some comments on rocket_state.h

5715521

adding some comments on sensor_data.h

1305dc2

making slight modifications to systems.h comments

cbcb6cf

commenting through GPS thread in systems.cpp

dc1c274

finishing comments for threads

27dc54f

finishing documenting systems.cpp!

c56add9

Merge pull request #221 from ISSUIUC/docs/flight_systems_docs

a5eab74

Adding comments to flight systems docs

MuhammadAli8209 requested review from mpkarpov-ui and tjmcmanamen38 August 8, 2026 21:16

mpkarpov-ui requested changes Aug 9, 2026

View reviewed changes

tjmcmanamen38 requested changes Aug 10, 2026

View reviewed changes

mpark108 added 4 commits August 13, 2026 11:12

making some changes due to requested changes

bc1ac59

making changes on systems.cpp

b1f5165

removing the unnecessary modifications to readme

12b30fa

removing very unnecessary pyro comments

e1eb189

		* @brief Packages and streams unified high-fidelity launch session artifacts down telemetry pipelines.
		* @details Interleaves structure elements, system metadata tracking logs, and direct checksum validation.



		bool FSMPyroAction::conditions_met(FSMState fsm_state, float cur_tilt, uint8_t cur_motor, float cur_time_since_launch, float cur_vx) const {
		// Pyro must be enabled.

Uh oh!

Conversation

MuhammadAli8209 commented Aug 8, 2026

Uh oh!

github-actions Bot commented Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mpkarpov-ui left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tjmcmanamen38 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

github-actions Bot commented Aug 8, 2026 •

edited

Loading