diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml new file mode 100644 index 00000000..4d33f06c --- /dev/null +++ b/.github/workflows/manual.yml @@ -0,0 +1,32 @@ +name: Manual + +on: + pull_request: + paths: + - "docs/**" + - "CATS User Manual.pdf" + - ".github/workflows/manual.yml" + push: + branches: [main] + paths: + - "docs/**" + - "CATS User Manual.pdf" + - ".github/workflows/manual.yml" + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: typst-community/setup-typst@v4 + with: + typst-version: 0.15.1 + - name: Build PDF and HTML + run: node docs/build-manual.mjs + - name: Validate generated HTML + run: node docs/check-manual.mjs + - name: Check generated files are current + run: git diff --exit-code -- "CATS User Manual.pdf" docs/generated/manual.html diff --git a/CATS User Manual.pdf b/CATS User Manual.pdf index 2bf1232b..30ce07eb 100644 Binary files a/CATS User Manual.pdf and b/CATS User Manual.pdf differ diff --git a/docs/Chapters/1_RevisionHistory.typ b/docs/Chapters/1_RevisionHistory.typ deleted file mode 100644 index 21b5174b..00000000 --- a/docs/Chapters/1_RevisionHistory.typ +++ /dev/null @@ -1,46 +0,0 @@ -#import "../styles.typ": * - -= Revision History - -#cats-table( - table( - columns: (0.2fr, 0.1fr, 0.7fr,), - inset: (x: 4pt, y: 4.5pt), - align: (x, y) => left + top, - stroke: 0.35pt + luma(45%), - fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, - [Date], - [Version], - [Comment], - [15 Dec 2022], - [1.0.0], - [Initial release], - [05 Mar 2023], - [1.1.0], - [Addressing first round of feedback; added telemetry explanations], - [16 Jul 2023], - [2.0.0], - [Added explanations for new hardware version; added support for sensor tab on the ground station; added explanations for test button; added bootloader explanations on ground station], - [21 Jan 2026], - [2.1.0], - [Added regulatory info; Added more information on software updates and flight recorder settings; fixed typos], - [21 Jun 2026], - [2.1.1], - [Added section on Ground Station USB Data Streaming], - [09 Aug 2026], - [2.1.2], - [Corrected Ground Station flash memory capacity and CATS Vega dimensions], - table.hline(y: 1, stroke: 0.5pt + black), - table.hline(y: 2, stroke: 0.5pt + black), - table.hline(y: 3, stroke: 0.5pt + black), - table.hline(y: 4, stroke: 0.5pt + black), - table.hline(y: 5, stroke: 0.5pt + black), - table.hline(y: 6, stroke: 0.5pt + black), - table.hline(y: 7, stroke: 0.5pt + black) -), - caption: [Revision History], - continued: false, - breakable: false, -) - -#pagebreak() diff --git a/docs/Chapters/2_Introduction.typ b/docs/Chapters/2_Introduction.typ index 7f9d58e7..ac423908 100644 --- a/docs/Chapters/2_Introduction.typ +++ b/docs/Chapters/2_Introduction.typ @@ -2,15 +2,15 @@ = Introduction -Welcome to the CATS flight computer! The following pages explain the CATS System, which consists of the CATS Vega flight computer and the CATS Ground Station, so that you can use it in your rocket. Each component has a How to Use section that provides the information needed to launch your rocket. Other sections provide advanced information that is not required for basic use of the CATS System.#linebreak() If you have any feedback, suggestions, or need further help with the CATS System, do not hesitate to contact us on our #link("https://discord.gg/r7ErmSNvsy")[Discord server]#footnote[#metadata(none) #link("https://discord.gg/r7ErmSNvsy")[https://discord.gg/r7ErmSNvsy]]. This is the first release of the manual and will be improved based on your feedback!#linebreak() The entire CATS ecosystem is open source. You can find all code and hardware designs on our #link("https://github.com/catsystems")[GitHub page]#footnote[#link("https://github.com/catsystems")[https://github.com/catsystems]]. +Welcome to the CATS User Manual. The following pages explain the CATS System so that you can install, configure, test, fly, and recover a rocket using the CATS Vega flight computer and CATS Ground Station. Each component has a practical operating section, while later chapters provide additional technical detail.#linebreak() If you have feedback, suggestions, or need further help, contact us on our #link("https://discord.gg/r7ErmSNvsy")[Discord server]. The CATS ecosystem is open source; source code and hardware designs are available on our #link("https://github.com/catsystems")[GitHub page]. == Coverage of This Manual -This manual covers the use of the CATS Vega flight computer and its Ground Station. It explains how the flight computer works, how to connect it to a #gls("Power Supply", cap: false) and deployment actuators, and how to configure it for your flight trajectory.#linebreak() This manual does not cover everything that can be done with the CATS System. In particular, it does not explain how to modify the software or hardware, or how the software works in detail. For further information about those topics, contact us on our #link("https://discord.gg/r7ErmSNvsy")[Discord server]#xref("fn:note1"). +This manual covers the use of the CATS Vega flight computer and its Ground Station. It explains how the flight computer works, how to connect it to a #gls("Power Supply", cap: false) and deployment actuators, and how to configure it for your flight trajectory.#linebreak() This manual does not cover everything that can be done with the CATS System. In particular, it does not explain how to modify the software or hardware, or how the software works in detail. For further information about those topics, contact us on our #link("https://discord.gg/r7ErmSNvsy")[Discord server]. == Module Overview -The CATS System has three main components. #linebreak()#v(-1.8pt) *CATS Vega:* The flight computer installed inside your rocket.#linebreak() *Ground Station:* The receiver that displays flight data in real time and helps you track your rocket after it has landed.#linebreak() *Configurator:* The computer application used to configure the CATS Vega and visualize completed flights.#linebreak() +The CATS System has three main components. #linebreak()#v(-1.8pt) *CATS Vega:* The flight computer installed inside your rocket.#linebreak() *Ground Station:* The receiver that displays and records telemetry, supports recovery, and controls bench testing.#linebreak() *Configurator:* The desktop application used to configure and update the CATS Vega, review a configuration before flight, manage profiles, and analyze completed flights.#linebreak() == Basic Functionality diff --git a/docs/Chapters/3_Vega.typ b/docs/Chapters/3_Vega.typ index 25443143..da3d6a18 100644 --- a/docs/Chapters/3_Vega.typ +++ b/docs/Chapters/3_Vega.typ @@ -4,7 +4,7 @@ This section describes how the flight computer works and how to configure it for a flight. The How to Use section explains its basic features. For more detailed information, refer to Section #xref("sec:AdvancedInfo"). -#cats-figure(image("../images/How To Use/Vega/Vega_HW.jpeg", width: 60%), caption: [CATS Vega]) +#cats-figure(doc-image("How To Use/Vega/Vega_HW.jpeg", width: 60%), caption: [CATS Vega]) == Hardware @@ -63,7 +63,7 @@ This section describes how the flight computer works and how to configure it for This section provides a quick hardware overview and shows the location of each port. The numbered markers in Figure #xref("fig:VegaHWSpecs") correspond to the following list.#linebreak()#v(-1.8pt) -#grid(columns: (63%, 1fr, 33%), [ +#responsive-split(columns: (63%, 1fr, 33%), [ #enum(tight: false, [ *Switch Port*; Connect a manual switch between the two terminals. @@ -105,8 +105,8 @@ This section provides a quick hardware overview and shows the location of each p *Antenna Connector*; Connect an antenna here so that the CATS Vega can transmit data to the Ground Station. ] ) -], [], [ -#cats-figure(image("../images/How To Use/Vega/VEGA-Hardware-optimized.png", width: 100%), caption: [CATS Vega board hardware specifications]) +], [ +#cats-figure(doc-image("How To Use/Vega/VEGA-Hardware-optimized.png", width: 100%), caption: [CATS Vega board hardware specifications]) ]) == Working Principle @@ -117,7 +117,7 @@ This section briefly introduces the operating principles needed to understand th #metadata(none) The finite state machine (#gls("FSM", cap: false)), shown in Figure #xref("fig:FSM"), controls the outputs of the Vega flight computer. When the flight computer is turned on, it starts in the Calibrating state. Every flight follows the sequence of states shown in Figure #xref("fig:FSM"). Whenever a state transition occurs, the associated event is triggered. -#cats-figure(image("../images/Working Principle/Finite_State_Machine.png", width: 13cm), caption: [Finite State Machine controlling the CATS software.]) +#cats-figure(doc-image("Working Principle/Finite_State_Machine.png", width: 13cm), caption: [Finite State Machine controlling the CATS software.]) Each event can trigger one or more actions, such as a #gls("pyro", cap: false) channel, #gls("servo", cap: false) channel, or timer. Use the Configurator to assign actions to events, as described in Section #xref("sec:DescriptionOfConfigurator"). @@ -146,6 +146,7 @@ Each event can trigger one or more actions, such as a #gls("pyro", cap: false) c caption: [FSM Transition Specifications], continued: false, breakable: false, + class-name: "fsm-transitions", ) With this setup for state changes, the flight has a strictly controlled order. The Main event can only be thrown after the #gls("apogee", cap: false) event. Events are also *unique*; during a flight only one event can be thrown.#linebreak() @@ -222,187 +223,132 @@ Now that the hardware and software have been introduced, this section explains h === Connection to Your Computer -Before connecting your CATS Vega to your computer, download the Configurator from our #link("https://github.com/catsystems/cats-configurator/releases/")[releases page]. Drivers are usually not required. If your computer does not recognize the device, refer to the troubleshooting steps in our #link("https://github.com/catsystems/cats-embedded/wiki/Installation")[wiki]#footnote[#link("https://github.com/catsystems/cats-embedded/wiki/Installation")[https://github.com/catsystems/cats-embedded/wiki/Installation]]. +Before connecting your CATS Vega to your computer, download the Configurator from our #link("https://github.com/catsystems/cats-configurator/releases/")[releases page]. Drivers are usually not required. If your computer does not recognize the device, refer to the troubleshooting steps in our #link("https://github.com/catsystems/cats-embedded/wiki/Installation")[wiki]#source-note("https://github.com/catsystems/cats-embedded/wiki/Installation"). === Description of the Configurator -#metadata(none) The Configurator allows you to configure the CATS System from your computer. Download the latest stable version from the #link("https://github.com/catsystems/cats-configurator/releases/")[releases page]#footnote[#link("https://github.com/catsystems/cats-configurator/releases/")[https://github.com/catsystems/cats-configurator/releases]]. Release candidates are marked accordingly and should be used only to test new features.#linebreak()#v(-1.8pt) *Home Tab*#linebreak()#v(-1.8pt) The Home tab appears when the Configurator starts. If the flight computer is already connected to your computer, select the correct communication port (label 2 in Figure #xref("fig:GUIHome")) and select Connect. If the connection times out, confirm that you selected the correct device. If several flight computers are connected, make sure that you are configuring the intended one. Until a flight computer is connected, the other tabs remain disabled (label 6), and the Configurator indicates that no board is connected (labels 5 and 7).#linebreak() If the required communication port does not appear in the dropdown menu, select Refresh (label 1). If the port still does not appear, refer to our #link("https://github.com/catsystems/cats-embedded/wiki/Installation")[wiki] for troubleshooting steps.#linebreak() +#metadata(none) The Configurator is the desktop application used to configure the CATS Vega, inspect its status, manage configuration profiles, run a preflight review, update firmware, and analyze flight logs. Download the latest release from the #link("https://github.com/catsystems/cats-configurator/releases/")[Configurator releases page]#source-note("https://github.com/catsystems/cats-configurator/releases"). -#cats-table( - table( - columns: (0.3fr, 0.7fr,), - inset: (x: 4pt, y: 4.5pt), - align: (x, y) => left + top, - stroke: 0.35pt + luma(45%), - fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, - [1: Refresh Button], - [Refreshes the communication ports shown under label 2], - [2: Com Port Selection], - [Selects the communication port used to connect to the CATS Vega], - [3: Connect Button], - [Connects to the CATS Vega], - [4: Home Screen], - [Displays general information about the Configurator], - [5: Connection Status], - [Indicates that the flight computer is not currently connected], - [6: Navigation], - [Remains disabled until a flight computer is connected, then provides navigation between tabs], - [7: Connection Status], - [Shows the connection status], - [8: Flight Log Graph], - [Loads a CATS flight log (.cfg) file for plotting. See Section #xref("sec:GeneratePlots") for more information] -), - caption: [Overview of the different Settings for the Home Tab], - continued: false, - breakable: false, -) - -#cats-figure(image("../images/How To Use/Configurator/GUI_Home.jpg", width: 100%), caption: [Home Menu.]) +When exactly one compatible Vega is connected, the Configurator selects it and connects automatically. If no automatic connection is made, use the device selector in the upper-right corner, choose the intended Vega, and select *Connect*. Use the refresh button if a newly connected device is not listed. When several Vegas are connected, always verify the selected device before changing or saving a configuration. -*Configuration Tab*#linebreak()#v(-1.8pt) This tab displays the flight computer's status and allows you to configure its parameters. Figure #xref("fig:GUIConfig") shows the Configuration tab, and the following table explains each label. - -#cats-figure(image("../images/How To Use/Configurator/GUI_Config.png", width: 100%), caption: [Configuration Menu.]) +The left navigation provides the following work areas: #cats-table( table( - columns: (0.2fr, 0.23fr, 0.57fr,), + columns: (0.28fr, 0.72fr,), inset: (x: 4pt, y: 4.5pt), align: (x, y) => left + top, stroke: 0.35pt + luma(45%), fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, - table.cell(rowspan: 3, fill: luma(94%))[#strong[1: Communication Port]], - [Refresh Button], - [Used to refresh the communication port list], - [Com Port], - [Shows the communication port selected], - [Connection Button], - [Shows the connection status and allows you to connect or disconnect], - table.cell(rowspan: 4, fill: luma(94%))[#strong[2: Navigation]], [Configuration], - [The current tab], - [Events], - [Event tab, described on the next page], - [Timers], - [Timer tab, described on the next page], + [Flight settings, telemetry, testing, recorder settings, live board status, and hardware information.], + [Events & Timers], + [Actions assigned to flight events and the four configurable timers.], + [Profiles], + [Export the connected board configuration, compare another profile, and apply compatible settings.], + [Preflight], + [A read-only review of the configuration, warnings, event sequence, timers, and outputs.], [#gls("CLI", cap: false)], - [Access to the #gls("CLI", cap: false) for advanced commands, described on the next page], - table.cell(rowspan: 7, fill: luma(94%))[#strong[3: General]], - [Main Altitude], - [Sets the desired height above ground level at which the #gls("main chute", cap: false) is deployed], - [#gls("liftoff", cap: true) Detection Acceleration], - [User-defined acceleration threshold above which liftoff is detected. We recommend 40 $m/s^2$ for most flights], - [Initial Position #gls("servo", cap: true) 1], - [Initial angle of the #gls("servo", cap: false) connected to #gls("servo", cap: false) port 1. If no #gls("servo", cap: false) is connected, no value is required. At startup, the flight computer drives the #gls("servo", cap: false) to this position.], - [Initial Position #gls("servo", cap: true) 2], - [Same as for #gls("servo", cap: false) 1 but for the second channel.], - [Backup Config], - [Saves a configuration file to your computer. Select Load Config to load this file onto the flight computer.], - [Load Config], - [Loads a previously backed-up configuration from your computer onto the flight computer.], - [Reset Settings], - [Set the default parameters of the flight computer.], - table.hline(y: 1, stroke: 0.5pt + black), - table.hline(y: 4, stroke: 0.5pt + black), - table.hline(y: 8, stroke: 0.5pt + black) + [Direct access to advanced flight-computer commands.], + [Flight Logs], + [Open local or onboard `.cfl` logs, generate plots, export data, or open a log in CATS Flights.], + [Firmware Updates], + [Detect supported devices, retrieve official releases, and install or prepare firmware.], + [Flights], + [Open CATS Flights in the default browser.] ), - caption: [Overview of the Configuration Tab], + caption: [Configurator navigation], continued: false, breakable: false, -) +) -#pagebreak() +==== Configuration -#cats-table( - table( - columns: (0.2fr, 0.23fr, 0.57fr,), - inset: (x: 4pt, y: 4.5pt), - align: (x, y) => left + top, - stroke: 0.35pt + luma(45%), - fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, - table.cell(rowspan: 4, fill: luma(94%))[#strong[4: Info]], - [System Time], - [The elapsed system time since startup, in milliseconds], - [State], - [The current flight state of the board], - [Voltage], - [The battery voltage (if no battery is connected, a value below 1 V is shown)], - [State Estimation], - [The currently estimated height above ground level, velocity and acceleration], - table.cell(rowspan: 2, fill: luma(94%))[#strong[5: Telemetry]], - [Link Phrase], - [A link phrase containing 4 to 16 characters. It must match the link phrase configured on the Ground Station.], - [Enable Telemetry], - [Set to ON or OFF to enable or disable telemetry.], - table.cell(rowspan: 2, fill: luma(94%))[#strong[6: Testing]], - [Enable Testing Mode], - [If this is set to ON, the flight computer enters testing mode after its next reboot. It must then be armed through telemetry using the Ground Station. Read Section #xref("sec:Testing") thoroughly before using testing mode.], - [Testing Phrase], - [A testing phrase containing 4 to 16 characters. It must match the testing phrase configured on the Ground Station. Read Section #xref("sec:Testing") thoroughly before using testing mode.], - table.cell(rowspan: 4, fill: luma(94%))[#strong[7: Hardware Info]], - [Status], - [Connection status of the board], - [Board], - [CATS Board Name], - [Code Version], - [Current code version], - [Telemetry Code Version], - [Current code version on the telemetry chip], - table.cell(rowspan: 2, fill: luma(94%))[#strong[8: Save Settings]], - [Save], - [Save the current settings to the board. *Attention:* if Save is not pressed, the values are not saved to the board!], - [Refresh], - [Refresh the displayed values. When this button is pressed, the saved values from the flight computer are fetched and shown.], - table.hline(y: 1, stroke: 0.5pt + black), - table.hline(y: 5, stroke: 0.5pt + black), - table.hline(y: 7, stroke: 0.5pt + black), - table.hline(y: 9, stroke: 0.5pt + black), - table.hline(y: 13, stroke: 0.5pt + black) -), - caption: [Overview of the Configuration Tab (Cont.)], - continued: true, - breakable: false, -) +The Configuration page groups flight settings into General, Telemetry, Testing, Recording, Info, and Hardware Info panels. The General panel contains the main-deployment altitude, liftoff threshold, and initial servo positions. For most flights, use a liftoff threshold of 40 $m/s^2$ unless testing with the complete rocket shows that another value is required. The Telemetry and Testing panels contain the enable controls and phrases used by the Ground Station. -#metadata(none) +Changes shown in the Configurator are not persistent until *Save* is selected. Use *Refresh* to discard unsaved edits and reload the values stored on the Vega. *Reset Config* restores the default configuration after confirmation. -#pagebreak() +==== Events & Timers -*Event Tab*#linebreak()#v(-1.8pt) This tab shows the actions configured for each event. Section #xref("sec:FSM") describes the events in detail. Up to eight actions can be assigned to each event: Liftoff, Burnout, Apogee, Main Deployment, Touchdown, Custom 1, and Custom 2. Select Add Action under an event to assign a new action. To avoid missing flight data, we recommend assigning Recorder On to Liftoff and Recorder Off to Touchdown.#linebreak() In the example shown in Figure #xref("fig:GUIEvents"), Liftoff, Apogee, Main Deployment, and Touchdown have mapped actions. At Liftoff, the recorder is enabled. At #gls("apogee", cap: false), #gls("pyro", cap: false) channel 1 is activated. At Main Deployment, #gls("pyro", cap: false) channel 2 is activated. At Touchdown, the recorder is disabled.#linebreak() Figure #xref("fig:GUIEventSel") shows the pop-up menu opened by selecting Add Action. Select the action type in the upper section, then configure its behavior in the lower section.#linebreak() To remove an action, select the cross beside it. Select the gear icon to reconfigure an action. Select *Save* after making changes.#linebreak() +The Events & Timers page shows all flight events and their assigned actions, followed by the four timers. Select *Add Action* to add an output, recorder command, or delay to an event. Existing actions can be edited or removed. Up to eight actions can be assigned to each event. Select *Save* after changing events or timers. + +Each timer has a start event, a duration, and an event to trigger when the duration expires. A timer can provide a backup event or trigger Custom 1 or Custom 2 for a payload sequence. Triggering an event through a timer does not force the flight-state estimator into the corresponding state. #note[ -*Note:* The custom events can only be triggered as described below in the Timers section. +*Note:* Flight events are unique during normal operation. If both the estimator and a timer could trigger the same event, only the first occurrence is processed. ] -#cats-figure(image("../images/How To Use/Configurator/GUI_Events.jpg", width: 100%), caption: [Event Menu.]) +#cats-figure( + figure-stack( + spacing: 12pt, + breakable: true, + subfigure( + doc-image("How To Use/Configurator/Configurator_Configuration.png", width: 100%, alt: "Configurator Configuration page connected to a CATS Vega"), + [Review and edit the connected Vega configuration.], + "a", + ), + subfigure( + doc-image("How To Use/Configurator/Configurator_Events_Timers.png", width: 100%, alt: "Configurator Events and Timers page"), + [Review event actions and timer configuration.], + "b", + ), + ), + caption: [Configurator Configuration and Events & Timers pages], + breakable: true, +) + +==== Profiles -#pagebreak() +#metadata(none) The Profiles page can export the complete connected-board configuration as a JSON profile. Opening another profile shows a setting-by-setting comparison with the connected Vega, including differences in configuration, events, timers, and recorder settings. Review compatibility warnings before applying a profile. You can apply the full compatible profile or individual differing settings, then save the resulting configuration to the board. -#cats-figure(image("../images/How To Use/Configurator/GUI_EventSel.jpg", width: 100%), caption: [Configuring an Event in the Event Menu.]) +==== Preflight -*Timers*#linebreak()#v(-1.8pt) Use this tab to configure the four available timers. Enable or disable each timer with the yellow button in the upper-right corner of its panel. #linebreak() After enabling a timer (Timer 1 in Figure #xref("fig:GUITimers")), configure its start event, duration in milliseconds, and end event. In the example, the start event is #gls("liftoff", cap: true), the duration is 10000 ms, and the end event is #gls("apogee", cap: true). At liftoff, a 10-second timer starts and triggers the #gls("apogee", cap: false) event when it expires. This triggers the event without placing the flight computer in the Apogee state.#linebreak() +#metadata(none) The Preflight page reads the saved board configuration and produces a report without changing it. Run Preflight after saving the final configuration. Review every error and warning, especially testing mode, telemetry and recording status, deployment actions, liftoff threshold, timer cycles, and event ordering. The event timeline summarizes which actions run at each flight event and which active timers may trigger additional events. -#note[ -*Note:* Events are unique, meaning that if a timer is used to trigger apogee, only one apogee event will be thrown by the flight computer. It will either be the timer or the event from the estimation, whichever is thrown first. -] +Preflight is an additional configuration review, not a substitute for continuity checks, deployment-system testing, range procedures, or a redundant recovery system. -*Custom Events*#linebreak()#v(-1.8pt) Two custom events are available. To activate one, configure a timer whose end event is the desired custom event. This allows you to execute actions at an arbitrary time.#linebreak() This is particularly useful for payload experiments. For example, to actuate a device 10 seconds after apogee, configure a timer that starts at apogee, runs for 10 seconds, and triggers Custom 1. Then assign the desired actions to that event. +#cats-figure( + figure-stack( + spacing: 12pt, + breakable: true, + subfigure( + doc-image("How To Use/Configurator/Configurator_Profiles.png", width: 100%, alt: "Configurator Profiles page showing connected-board settings"), + [Inspect the connected-board profile or compare another profile before applying it.], + "a", + ), + subfigure( + doc-image("How To Use/Configurator/Configurator_Preflight.png", width: 100%, alt: "Configurator Preflight page showing a successful read-only review"), + [Run the read-only Preflight review after saving the final configuration.], + "b", + ), + ), + caption: [Configurator Profiles and Preflight pages], + breakable: true, +) -#pagebreak() +==== CLI + +The CLI page sends commands directly to the connected Vega. It is intended for advanced inspection and troubleshooting; normal configuration should be performed through the other pages. Common commands are listed in Section #xref("sec:CLI"). -#cats-figure(image("../images/How To Use/Configurator/GUI_Timers.jpg", width: 100%), caption: [Timer Menu.]) +==== Flight Logs -*CLI*#linebreak()#v(-1.8pt) The CLI tab allows the user to send commands directly to the CATS board. Section #xref("sec:CLI") explains all supported commands. Figure #xref("fig:GUICLI") shows the CLI. +#metadata(none) The Flight Logs page accepts one Vega `.cfl` file selected through the file picker or dropped anywhere in the Configurator window. When a Vega USB drive is mounted, the page also lists its onboard logs. An onboard log can be viewed locally, saved as a copy, deleted from the Vega, or opened in CATS Flights. -#cats-figure(image("../images/How To Use/Configurator/GUI_CLI.jpg", width: 100%), caption: [Command Line Interface.]) +After opening a log, use *Export CSV* for tabular data or *Export HTML* for interactive plots. *Open in Flights* hands the selected log to CATS Flights through the local browser; the log remains on the computer unless it is explicitly saved or shared there. + +#cats-figure( + doc-image("How To Use/Configurator/Configurator_Flight_Logs.png", width: 100%, alt: "Configurator Flight Logs page listing an onboard Vega log"), + caption: [Configurator Flight Logs page with a connected Vega], +) === Mounting -#grid(columns: (60%, 1fr, 33%), [ -The CATS Vega *does not* require a specific mounting orientation. The system automatically detects the gravity vector for internal state estimation, so you can mount the board in any orientation.#linebreak() The board has a length of 100 mm, a width of 33 mm and a total height of 15 mm. Three mounting holes secure the system to the rocket. The mounting holes are spaced 60 mm by 27 mm and are designed for M3 screws. Use spacers to prevent the electronics from touching the rocket. Download the system's 3D files from our #link("https://github.com/catsystems/cats-hardware/tree/main/CATS-Vega/3D")[GitHub repository]#footnote[#link("https://github.com/catsystems/cats-hardware/tree/main/CATS-Vega/3D")[https://github.com/catsystems/cats-hardware/tree/main/CATS-Vega/3D]].#linebreak() For reliable radio reception during flight, pay close attention to the area surrounding each antenna. Install the CATS flight computer in a radio-transparent section of the rocket, such as fiberglass or cardboard. Do not install it in a carbon-fiber section, which blocks #gls("RF", cap: false) signals. Ensure that the onboard #gls("patch antenna", cap: false) has a clear view of the sky for optimal #gls("GNSS", cap: false) reception, and keep the telemetry antenna away from metal objects. +#responsive-split(columns: (60%, 1fr, 33%), [ +The CATS Vega *does not* require a specific mounting orientation. The system automatically detects the gravity vector for internal state estimation, so you can mount the board in any orientation.#linebreak() The board has a length of 100 mm, a width of 33 mm and a total height of 15 mm. Three mounting holes secure the system to the rocket. The mounting holes are spaced 60 mm by 27 mm and are designed for M3 screws. Use spacers to prevent the electronics from touching the rocket. Download the system's 3D files from our #link("https://github.com/catsystems/cats-hardware/tree/main/CATS-Vega/3D")[GitHub repository]#source-note("https://github.com/catsystems/cats-hardware/tree/main/CATS-Vega/3D").#linebreak() For reliable radio reception during flight, pay close attention to the area surrounding each antenna. Install the CATS flight computer in a radio-transparent section of the rocket, such as fiberglass or cardboard. Do not install it in a carbon-fiber section, which blocks #gls("RF", cap: false) signals. Ensure that the onboard #gls("patch antenna", cap: false) has a clear view of the sky for optimal #gls("GNSS", cap: false) reception, and keep the telemetry antenna away from metal objects. After power-up, the system detects the up direction once it is stable. A beeping pattern and the Ground Station indicate when the flight computer enters the #gls("Ready", cap: false) state. In this state, the flight computer is armed and waiting for #gls("liftoff", cap: false). Do not move the rocket, and follow all safety guidelines. At this stage, the flight computer can be disarmed only by switching it off. For more information about calibration, refer to Sections #xref("sec:EstAlg") and #xref("sec:FSM").#linebreak() -], [], [ -#cats-figure(image("../images/How To Use/Vega/Mounting_Img.png", width: 80%), caption: [CATS Vega board with the mounting hole and dimensions.]) +], [ +#cats-figure(doc-image("How To Use/Vega/Mounting_Img.png", width: 80%), caption: [CATS Vega board with the mounting hole and dimensions.]) ]) #warning[ @@ -413,7 +359,7 @@ After power-up, the system detects the up direction once it is stable. A beeping The CATS Vega has one battery port, one switch port, two #gls("pyro", cap: false) channels, two #gls("servo", cap: false) channels, and one low-level #gls("I/O", cap: false). The following sections briefly explain each port. Table #xref("tab:HowToAct") summarizes the most important parameters. For more information about the board hardware, refer to Section #xref("sec:VegaHW") and the labeled board diagram in Figure #xref("fig:VegaHWSpecs").#linebreak()#linebreak()#v(1.8pt) -*Battery Port*#linebreak()#v(-1.8pt) The battery port supports voltages between 7 and 25 volts. For LiPo and Li-ion batteries, this corresponds to 2- to 6-cell battery packs. The battery port is protected against reverse polarity.#linebreak()#linebreak()#v(1.8pt) +*Battery Port*#linebreak()#v(-1.8pt) The battery port supports 7 to 24 volts. Use a 2- to 5-cell LiPo or Li-ion battery and ensure that its actual voltage remains within this range. The battery port is protected against reverse polarity.#linebreak()#linebreak()#v(1.8pt) *Switch Port*#linebreak()#v(-1.8pt) The switch port allows the user to add a mechanical switch to the system. If this switch is turned off, the system is fully disconnected from power.#linebreak() @@ -504,16 +450,16 @@ Connect the flight computer to your computer. Open the Configurator and connect to the board as described in Section #xref("sec:DescriptionOfConfigurator"). ], [ -In the Configuration tab, set the #gls("liftoff", cap: false) threshold. We recommend using a #gls("liftoff", cap: false) acceleration threshold of $40 m/s^2$, but make sure that it is around $20 m/s^2$ lower than your maximum expected acceleration. +On the *General* page, set the #gls("liftoff", cap: false) threshold. We recommend using a #gls("liftoff", cap: false) acceleration threshold of $40 m/s^2$, but make sure that it is around $20 m/s^2$ lower than your maximum expected acceleration. ], [ -In the Configuration tab, set the main altitude to your desired height. This is the height above ground level where the #gls("main chute", cap: false) will be deployed. +On the *General* page, set the main altitude to your desired height. This is the height above ground level where the #gls("main chute", cap: false) will be deployed. ], [ If you use a #gls("servo", cap: false) channel in either of your recovery mechanisms, it is now also the time to set the initial #gls("servo", cap: false) position. ], [ -In the Configurator's Configuration tab, set the link phrase for your CATS Vega. +On the Configurator's *General* page, set the link phrase for your CATS Vega. ], [ Make sure that the Testing Mode is disabled. @@ -522,7 +468,7 @@ Make sure that the Testing Mode is disabled. Save the settings. ], [ -Go to the Events tab. +Open the *Events & Timers* page. ], [ For the apogee event, set your deployment mechanism as described in #xref("sec:DescriptionOfConfigurator"). @@ -534,7 +480,7 @@ For the main deployment event, set your deployment mechanism as described in #xr Save the settings. ], [ -(Optional) Go to the Timers tab. +(Optional) On the same page, open the timers section. ], [ (Optional) Set the Timer One start event to #gls("liftoff", cap: false) and the Timer One end event to apogee. Set the time until apogee with 1-2 seconds margin. @@ -590,98 +536,17 @@ Launch your rocket! === How to Get the Data on Your Computer -After the flight, connect the board to a computer with a USB-C cable. The flight computer appears as a USB drive, allowing you to drag and drop the flight data onto your desktop. You can also drag the flight log directly into the Configurator to plot it.#linebreak() +After the flight, connect the board to a computer with a USB-C cable. The flight computer appears as a USB drive containing `.cfl` flight logs and their associated files. Copy the required files before disconnecting the board, or use the Configurator's Flight Logs page to browse, view, save, or delete onboard logs. -#cats-figure(image("../images/How To Use/Vega/StorageVega.png", width: 100%), caption: [USB drive when the CATS Vega is plugged into the user computer.]) +#cats-figure(doc-image("How To Use/Vega/StorageVega.png", width: 100%), caption: [USB drive when the CATS Vega is plugged into the user computer.]) === Visualizing the Flight Data -#metadata(none) To visualize flight data, open the Configurator and drag and drop the CATS flight log (`.cfg`). The Configurator immediately plots the important data: altitude, velocity, acceleration, angular velocity (x, y, and z), linear acceleration (x, y, and z), pressure, state changes, and actions.#linebreak() You can export the plots as `.html` files, which retain their zoom functionality when opened in a browser, or as `.csv` files for further processing.#linebreak()#v(-1.8pt) A legacy Python plotting tool is also available as a reference for custom implementations. It is described briefly in Section #xref("sec:GeneratePlotsPython"). +#metadata(none) Open the Configurator's Flight Logs page and choose or drop a `.cfl` flight log. The Configurator plots altitude, velocity, acceleration, angular velocity, linear acceleration, pressure, state changes, and actions. Export the data as `.csv` files for further processing or as an `.html` file with interactive plots. You can also open the log in CATS Flights. A legacy Python plotting tool is described in Section #xref("sec:GeneratePlotsPython") for users who need a customizable local workflow. === Software Updates -#metadata(none) The software is continuously improved, so install each new update when it is released. Updates are announced on our #link("https://discord.gg/r7ErmSNvsy")[Discord server]#footnote[#link("https://discord.gg/r7ErmSNvsy")[https://discord.gg/r7ErmSNvsy]]. To update the software, follow these steps: - -#enum(tight: false, - [ -Download and install the #link("https://www.st.com/en/development-tools/stm32cubeprog.html")[STM Programmer]#footnote[#link("https://www.st.com/en/development-tools/stm32cubeprog.html")[https://www.st.com/en/development-tools/stm32cubeprog.html]] (STM32CubeProg). -], - [ -Connect the CATS Vega with a USB-C cable. -], - [ -Start the Configurator, select the correct COM port, select Connect, and open the #gls("CLI", cap: false) tab described in Section #xref("sec:DescriptionOfConfigurator"). -], - [ -In the #gls("CLI", cap: false), enter #text(font: "DejaVu Sans Mono", size: 0.9em)[bl] and send the command. -], - [ -The CATS Vega will disconnect. Close the Configurator. -], - [ -Start the STM32 Programmer. -], - [ -In the upper-right corner of the programmer, select USB (Figure #xref("fig:SWUpdateInit")). -], - [ -On the right, select the appropriate USB port (Figure #xref("fig:SWUpdateUSB")). -], - [ -Select Connect (Figure #xref("fig:SWUpdateUSB")). -], - [ -Confirm that the upper-right corner shows that the programmer is connected to the board (Figure #xref("fig:SWUpdateConnected")). -], - [ -In the left navigation panel, select Erasing & Programming (Figure #xref("fig:SWUpdateProgram")). -], - [ -In the File path field, select the firmware file to flash (the filename ends in `.bin`). The latest release of the CATS software is available #link("https://github.com/catsystems/cats-embedded/releases")[here]#footnote[#link("https://github.com/catsystems/cats-embedded/releases")[https://github.com/catsystems/cats-embedded/releases]] (Figure #xref("fig:SWUpdateProgram")). -], - [ -Select Start Programming (Figure #xref("fig:SWUpdateProgram")). -], - [ -Wait for the "File Download Complete" pop-up (Figure #xref("fig:SWUpdateProgramFinished")). -], - [ -Disconnect and reconnect the board. Start the Configurator and verify that the version number has been updated. -], - [ -You've successfully updated the software! -] -) - -#warning[ -*Warning:* The steps above update only the Vega's flight-control software (#text(font: "DejaVu Sans Mono", size: 0.9em)[flight\_computer.bin]). The telemetry code (#text(font: "DejaVu Sans Mono", size: 0.9em)[telemetry.bin]) resides on another chip and cannot be updated via USB. Updating the telemetry software requires an STLINK-V3MINI debugger and a TC2030-IDC-NL 6-pin connector. -] - -#cats-figure( - stack(dir: ttb, spacing: 8pt, - [#align(center)[#block(width: 100%)[#subfigure(image("../images/How To Use/SoftwareUpdate/Programmer-Init.jpg", width: 100%), [Open the dropdown menu and select USB. The panel shown in the next image opens on the right.], "a") ]]], - [#align(center)[#block(width: 100%)[#subfigure(image("../images/How To Use/SoftwareUpdate/Programmer-USB.png", width: 100%), [Select the displayed USB port in the Port field, then select Connect.], "b") ]]] - ), - caption: [Flashing new software to the board.], - continued: false, -) - -#cats-figure( - stack(dir: ttb, spacing: 8pt, - [#align(center)[#block(width: 100%)[#subfigure(image("../images/How To Use/SoftwareUpdate/Programmer-Connected.png", width: 100%), [Confirm that the Connected status appears in the upper-right corner.], "c") ]]], - [#align(center)[#block(width: 100%)[#subfigure(image("../images/How To Use/SoftwareUpdate/Programmer-Erase-Programm.png", width: 100%), [Select Erasing & Programming on the left. Use Browse to select the appropriate `.bin` file, then select Start Programming.], "d") ]]] - ), - caption: [Flashing new software to the board (cont.).], - continued: true, -) - -#cats-figure( - stack(dir: ttb, spacing: 8pt, - [#align(center)[#block(width: 100%)[#subfigure(image("../images/How To Use/SoftwareUpdate/Programmer_Finished.JPG", width: 100%), [This message appears when the firmware has been flashed successfully.], "e") ]]] - ), - caption: [Flashing new software to the board (cont.).], - continued: true, -) +#metadata(none) Use the Configurator's Firmware Updates page for normal Vega updates. The complete procedure, including Ground Station and radio-receiver updates, is described in Section #xref("sec:FirmwareUpdates"). #pagebreak() @@ -701,19 +566,19 @@ You've successfully updated the software! [*Pattern*], [Bootup], [The flight computer has booted up.], - [#image("../images/How To Use/Beeping_Patterns/Beep-Bootup.png", width: 50%)], + [#doc-image("How To Use/Beeping_Patterns/Beep-Bootup.png", width: 50%, alt: "Bootup beeping pattern")], [#gls("Calibrating", cap: false) $arrow.r$ #gls("Ready", cap: false)], [The flight computer has switched from the #gls("Calibrating", cap: false) state to the #gls("Ready", cap: false) state.], - [#image("../images/How To Use/Beeping_Patterns/Beep-Moving-Ready.png", width: 50%)], + [#doc-image("How To Use/Beeping_Patterns/Beep-Moving-Ready.png", width: 50%, alt: "Calibrating to ready beeping pattern")], [#gls("Ready", cap: false)], [Calibration was successful, and the flight computer is in the #gls("Ready", cap: false) state.], - [#image("../images/How To Use/Beeping_Patterns/Beep-Ready.png", width: 50%)], + [#doc-image("How To Use/Beeping_Patterns/Beep-Ready.png", width: 50%, alt: "Ready beeping pattern")], [Testing], [The flight computer is in testing mode. This pattern sounds only after the computer is rebooted.], - [#image("../images/How To Use/Beeping_Patterns/Beep-Testing.png", width: 50%)], + [#doc-image("How To Use/Beeping_Patterns/Beep-Testing.png", width: 50%, alt: "Testing beeping pattern")], [Testing Armed], [The flight computer is in the armed testing state.], - [#image("../images/How To Use/Beeping_Patterns/Beep-Testing-Armed.png", width: 50%)], + [#doc-image("How To Use/Beeping_Patterns/Beep-Testing-Armed.png", width: 50%, alt: "Testing armed beeping pattern")], table.hline(y: 2, stroke: 0.5pt + black) ), caption: [Overview of state beeping patterns.], @@ -725,39 +590,6 @@ You've successfully updated the software! *Note:* The pitch axis shows only relative, unitless changes. ] -#pagebreak() - -#cats-table( - table( - columns: (0.15fr, 0.6fr, 0.15fr,), - inset: (x: 4pt, y: 4.5pt), - align: (x, y) => left + top, - stroke: 0.35pt + luma(45%), - fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, - [*Error*], - [*Description*], - [*Pattern*], - [Filter Error], - [A #gls("barometer", cap: false) or accelerometer error is present. If this error persists, *do not fly; the flight computer's functionality is compromised.*], - [TBD], - [Pyro Error], - [A configured pyrotechnic charge is not detected. If this error persists, *do not fly; the configured recovery mechanism will not work.*], - [TBD], - [Log Full], - [The flash chip is full. If you fly, the flight will not be recorded.], - [TBD], - [Telemetry Hot], - [The telemetry chip has reached 60 $degree$C and may be damaged.], - [TBD], - [Calibration Error], - [The calibration is faulty. *Do not fly!* Return to the rocket and reboot the flight computer to restart calibration.], - [TBD] -), - caption: [Overview of error beeping patterns.], - continued: false, - breakable: false, -) - #note[ *Note:* Bad calibrations usually happen when the flight computer is turned on and then rotated. Only turn the flight computer on once the rocket is in launch configuration and upright on the launch pad. ] diff --git a/docs/Chapters/4_GroundStation.typ b/docs/Chapters/4_GroundStation.typ index 674894c7..e7d952a3 100644 --- a/docs/Chapters/4_GroundStation.typ +++ b/docs/Chapters/4_GroundStation.typ @@ -4,13 +4,13 @@ The Ground Station is the counterpart to the CATS Vega. It receives data from the flight computer and sends commands to it. It displays the rocket's position, velocity, system health, and other important information in real time. This chapter explains how to use the Ground Station and describes its operating principle. -#cats-figure(image("../images/How To Use/Groundstation/Ground_Station.jpg", width: 80%), caption: [Ground Station]) +#cats-figure(doc-image("How To Use/Groundstation/Ground_Station.jpg", width: 80%), caption: [Ground Station]) == Hardware === Overview -The Ground Station is built around an ESP32-S2 microcontroller and features a transflective display that remains readable in bright sunlight. The onboard flash can store up to 1 MB of data, enough to track over an hour of flight data. +The Ground Station is built around an ESP32-S2 microcontroller and features a transflective display that remains readable in bright sunlight. It has 4 MB of internal flash, including a 1 MB FAT data partition for logs and firmware-transfer files. #pagebreak() @@ -26,7 +26,7 @@ The Ground Station is built around an ESP32-S2 microcontroller and features a tr [Microcontroller], [ESP32-S2], [Flash Memory], - [1 MB], + [4 MB internal; 1 MB data partition], [Battery], [Li-Ion 18650], [Power Consumption], @@ -53,70 +53,135 @@ This section covers the basic use of the Ground Station. For more advanced infor === Explanation of All Menus -#metadata(none) Use the joystick to move left, right, up, and down. Press the A button to open a menu or select an option, and press the B button to go back.#linebreak()#linebreak()#v(1.8pt) +#metadata(none) Use the joystick to move left, right, up, and down. Press A to open a menu, select an item, or confirm an action. Press B to go back. Arrows and hints at the edges of the display indicate when another page or action is available. -*Live Data*#linebreak()#v(-1.8pt) The Live Data screen shows all data received from the Vega flight computer, together with information about the data-link quality. - -#pagebreak() +#cats-figure( + doc-image("How To Use/Groundstation/GS_Main_Menu.png", width: 80%, outline: true, alt: "Ground Station main menu rendered by the simulator"), + caption: [Ground Station main menu], +) -#cats-figure(image("../images/How To Use/Groundstation/Ground_Station_Live_Data.jpg", width: 80%), caption: [Live Data of the Ground Station.]) +==== Live -The current flight-computer status appears at the top of the screen. The rocket's altitude, vertical velocity, GNSS coordinates, battery voltage, pyro continuity, and errors appear below it. +The Live screen shows telemetry from the connected Vega or Vegas. It displays flight state, altitude, vertical velocity, battery voltage, pyro continuity, errors, and radio-link information. Press Left for the GNSS view and Right for the downrange view. The downrange view uses the Ground Station's own GNSS position to show the rocket's relative direction and distance. -At the bottom, information about the telemetry link is displayed: +The link indicators include: #list(tight: false, [ -*AGE* - The packet age in seconds. If no packet is received for 5 seconds, the link disconnects. +*AGE* - Time since the last received packet. A link is treated as disconnected after five seconds without a packet. ], [ -*SNR* - Signal-to-noise ratio in dB. The link can remain active down to an SNR of -15 dB. A low SNR indicates substantial radio interference at your location. +*SNR* - Signal-to-noise ratio in dB. Lower values indicate a noisier radio environment. ], [ -*LQ* - Link quality as a percentage: the ratio of packets received to packets expected during the last 3 seconds. +*LQ* - Percentage of expected packets received during the recent measurement window. ], [ -*RSSI* - Received signal-strength indication in dBm. The link can remain active down to an RSSI of -110 dBm. As a rule of thumb, RSSI decreases by 6 dB each time the distance doubles. +*RSSI* - Received signal strength in dBm. More negative values indicate a weaker received signal. ] ) -*Recovery*#linebreak()#v(-1.8pt) The Recovery screen helps you locate the rocket after it lands. It uses the rocket's last known GNSS location, or its current location if the connection is still active. The Ground Station's onboard sensors calculate the distance and direction to the rocket. For accurate direction guidance, calibrate the device's compass outdoors near the launch site and away from large metal objects. The calibration procedure will be explained in a later version of this manual. #linebreak() The Recovery screen shows the #gls("GNSS", cap: false) coordinates of the Ground Station and the rocket, as well as the distance to the rocket. Follow the arrow to locate the rocket.#linebreak()#linebreak()#v(1.8pt) +#cats-figure( + responsive-split( + [#subfigure(doc-image("How To Use/Groundstation/GS_Live_Telemetry.png", width: 100%, outline: true, alt: "Ground Station live telemetry screen"), [GNSS telemetry from both receivers in Single mode.], "a")], + [#subfigure(doc-image("How To Use/Groundstation/GS_Live_Downrange.png", width: 100%, outline: true, alt: "Ground Station live downrange screen"), [Relative downrange distance and direction.], "b")], + columns: (46%, 1fr, 46%), + ), + caption: [Ground Station Live views], +) -*Testing*#linebreak()#v(-1.8pt) The Testing screen is used to perform manual tests. Refer to Section #xref("sec:Testing") for a detailed explanation of testing mode and how to use it.#linebreak()#linebreak()#v(1.8pt) +==== Recovery -#block(breakable: false)[ -*Data*#linebreak()#v(-1.8pt) Not yet implemented.#linebreak()#linebreak()#v(1.8pt) -] +The Recovery screen guides you toward the last valid GNSS position received from the rocket. It shows the selected rocket, distance, relative direction, and whether a usable location is available. Calibrate the Ground Station compass outdoors near the launch site and away from large metal objects before relying on direction guidance. -*Sensors*#linebreak()#v(-1.8pt) The Sensors screen displays raw data from the onboard IMU, magnetometer, and GNSS module. It also allows you to calibrate the magnetometer.#linebreak() Calibrate the magnetometer if the compass on the Recovery screen does not point north. On the Sensors screen, press A and follow the instructions. Slowly rotate the Ground Station in every direction while the progress appears on the screen. When progress reaches 100%, the calibration is complete and is saved on the Ground Station.#linebreak()#linebreak()#v(1.8pt) +In Dual receiver mode, press Up or Down to choose Link 1 or Link 2. Press Right to show a QR code for the selected last location; scan it with a phone to open the coordinates in a mapping application. If the other link also has a valid location, press Right again to switch QR-code pages. Press Left to return to direction guidance. -*Settings*#linebreak()#v(-1.8pt) The Ground Station settings are mostly self-explanatory, and tooltips are provided for every option. The current software version supports the following settings: +#cats-figure( + responsive-split( + [#subfigure(doc-image("How To Use/Groundstation/GS_Recovery.png", width: 100%, outline: true, alt: "Ground Station recovery direction screen"), [Direction and distance to the last received location.], "a")], + [#subfigure(doc-image("How To Use/Groundstation/GS_Recovery_QR.png", width: 100%, outline: true, alt: "Ground Station recovery location QR code"), [QR code for transferring the selected last location.], "b")], + columns: (46%, 1fr, 46%), + ), + caption: [Ground Station Recovery views], +) -#list(tight: false, - [ -*Timezone*: Choose your local timezone to display the correct time. -], - [ -*Stop Logging*: Choose whether the Ground Station stops logging after touchdown or continues logging indefinitely. -], - [ -*Version*: Ground Station software version number. -], - [ -*Bootloader*: Start the bootloader for software updates, as described in Section #xref("sec:gs_updates"). -], - [ -*Telemetry Mode*: Select Single or Dual mode, as described in Section #xref("sec:telemetrymode"). -], - [ -*Link Phrase 1*: Set the phrase that must match the link phrase configured on the CATS Vega. -], - [ -*Link Phrase 2*: Set the phrase that must match the second CATS Vega when tracking two flight computers. This setting is not used in Single mode. -], - [ -*Testing Phrase*: Set the phrase that must match the testing phrase configured on the CATS Vega. This phrase is required to use the testing mode described in Section #xref("sec:Testing"). -] +==== Testing + +The Testing screen arms testing mode and manually triggers configured flight events. Triggered events execute their assigned actions. Read Section #xref("sec:Testing") completely before using this screen. + +==== Data + +The Data screen lists logs stored on the Ground Station. An active recording is marked as active. Select a log to view its duration, maximum altitude and velocity, flight state, and recorded locations. When a valid location is available, open its QR-code page to transfer the coordinates to a phone. + +The options page can finalize the active log or delete a completed log after confirmation. Disconnect the Ground Station USB drive before deleting a log. Finalizing stops the active recording and closes its files; deleting permanently removes the selected completed log. + +#cats-figure( + responsive-split( + [#subfigure(doc-image("How To Use/Groundstation/GS_Data_Logs.png", width: 100%, outline: true, alt: "Ground Station list of recorded flight logs"), [Select a stored Ground Station flight log.], "a")], + [#subfigure(doc-image("How To Use/Groundstation/GS_Data_Details.png", width: 100%, outline: true, alt: "Ground Station flight-log statistics"), [Review recorded statistics and last locations.], "b")], + columns: (46%, 1fr, 46%), + ), + caption: [Ground Station Data views], +) + +==== Sensors + +The Sensors screen shows raw IMU, magnetometer, and GNSS readings. Press Right or Down to open the Compass / 3D Orientation page, which shows the Ground Station's heading, pitch, and roll. Press Left or Up to return to raw readings. + +Press A to start compass calibration and follow the on-screen instructions. Rotate the Ground Station slowly through multiple orientations, away from large metal objects and magnets. When calibration reaches 100%, confirm the result to save it. + +#cats-figure( + responsive-split( + [#subfigure(doc-image("How To Use/Groundstation/GS_Sensors_Readings.png", width: 100%, outline: true, alt: "Ground Station raw IMU and GNSS sensor readings"), [Raw IMU, magnetometer, and GNSS readings.], "a")], + [#subfigure(doc-image("How To Use/Groundstation/GS_Sensors_Orientation.png", width: 100%, outline: true, alt: "Ground Station compass and 3D orientation screen"), [Compass heading, pitch, and roll.], "b")], + columns: (46%, 1fr, 46%), + ), + caption: [Ground Station Sensors views], +) + +==== Settings + +Settings are divided into three pages. Move Left or Right while no setting is selected to change pages. + +#cats-table( + table( + columns: (0.22fr, 0.3fr, 0.48fr,), + inset: (x: 4pt, y: 4.5pt), + align: (x, y) => left + top, + stroke: 0.35pt + luma(45%), + fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, + [Page], [Setting], [Purpose], + [Telemetry], [Receiver Mode], [Single uses both receivers for one Vega; Dual assigns one Vega to each receiver.], + [Telemetry], [Link Phrase 1], [Phrase used by both receivers in Single mode or the left receiver in Dual mode.], + [Telemetry], [Link Phrase 2], [Phrase used by the right receiver in Dual mode.], + [Telemetry], [Test Phrase], [Phrase required to arm Vega testing mode.], + [Preferences], [Stop Logging], [Stop at landing or continue until manually finalized.], + [Preferences], [Time Zone], [Local offset from UTC.], + [Preferences], [Units], [Metric or imperial display units; recorded data remains metric.], + [Preferences], [Startup Animation], [Animated startup or static CATS logo.], + [System], [Firmware Versions], [Ground Station and both receiver-firmware versions.], + [System], [USB Drive], [View or disconnect the shared USB storage.], + [System], [Self-Test], [Factory-oriented automatic and guided hardware checks.], + [System], [Update Firmware], [Update the Ground Station application or both radio receivers.], + table.hline(y: 1, stroke: 0.5pt + black) +), + caption: [Ground Station settings], + continued: false, + breakable: true, +) + +#cats-figure( + responsive-split( + [#subfigure(doc-image("How To Use/Groundstation/GS_Settings_Telemetry.png", width: 100%, outline: true, alt: "Ground Station Telemetry settings page"), [Telemetry settings.], "a")], + [#subfigure(doc-image("How To Use/Groundstation/GS_Settings_Preferences.png", width: 100%, outline: true, alt: "Ground Station Preferences settings page"), [Display and recording preferences.], "b")], + columns: (46%, 1fr, 46%), + ), + caption: [Ground Station Telemetry and Preferences settings], +) + +#cats-figure( + doc-image("How To Use/Groundstation/GS_Settings_System.png", width: 46%, outline: true, alt: "Ground Station System settings page"), + caption: [Ground Station System settings], ) === Telemetry Modes @@ -157,7 +222,7 @@ The serial stream emits one line per newly received telemetry packet. All units ] ) -#cats-figure(image("../images/How To Use/Groundstation/Ground_Station_USB_Streaming.png", width: 95%), caption: [Ground Station telemetry data from both radio links streamed over the USB serial port.]) +#cats-figure(doc-image("How To Use/Groundstation/Ground_Station_USB_Streaming.png", width: 95%), caption: [Ground Station telemetry data from both radio links streamed over the USB serial port.]) #pagebreak() @@ -167,16 +232,10 @@ The Ground Station is powered by a Li-ion 18650 battery. A fully charged battery === How to Get the Data on Your Computer -Like the CATS Vega, the Ground Station is recognized as a mass-storage device when connected to a computer. Open the device folder and drag the recorded logs to your preferred location. Ground Station logs are stored as `.csv` files. - -#cats-figure(image("../images/How To Use/Groundstation/Ground_Station_Logs.png", width: 95%), caption: [Ground station data when connecting the ground station to the user computer.]) - -#pagebreak() +When connected by USB and not actively recording, the Ground Station shares its data partition as the `CATS GS` USB drive. Open the drive and copy the required `.csv` logs to the computer. The firmware reclaims the filesystem automatically when recording starts and shares it again after the log is finalized. Close files before recording or updating firmware, and use *Settings* $arrow.r$ *System* $arrow.r$ *USB Drive* when the drive needs to be disconnected manually. === Software Updates -#metadata(none) To update the Ground Station software, enter #gls("DFU", cap: false) mode. First, connect the Ground Station to your computer. In the Settings panel, select Bootloader. A large USB symbol appears on the screen, and a mass-storage device named SAOLA1RBOOT appears on the computer. Drag the firmware file into this folder to overwrite the old file. #linebreak() You can also enter the bootloader using the hardware controls. Remove the Ground Station casing and connect the Ground Station to your computer. Quickly press the reset button, followed by the boot button. The SAOLA1RBOOT mass-storage device will appear on your computer. Drag the firmware file onto the device. #linebreak() Firmware filenames end in `.UF2`. The latest Ground Station firmware can be downloaded from our repository. - -#cats-figure(image("../images/How To Use/Groundstation/Ground_Station_DFU.png", width: 95%), caption: [SAOLA1RBOOT mass storage device when successfully changing to the #gls("DFU", cap: false) Mode]) +#metadata(none) Use the Configurator's Firmware Updates page for normal Ground Station and radio-receiver updates. See Section #xref("sec:FirmwareUpdates") for the complete preparation, installation, verification, and recovery procedures. #pagebreak() diff --git a/docs/Chapters/5_Example.typ b/docs/Chapters/5_Example.typ index 9de148ce..66bddb47 100644 --- a/docs/Chapters/5_Example.typ +++ b/docs/Chapters/5_Example.typ @@ -1,87 +1,73 @@ #import "../styles.typ": * -= Example Configuration of the CATS Vega + Ground Station - -#metadata(none) This chapter presents two example configurations, showing both the relevant Configurator settings and the corresponding hardware setup. #linebreak() The first example is a simple configuration with a drogue chute and a main chute. The second example is intended for more advanced rockets and includes custom events. - -== Simple Example Configuration - -For the simple example, assume the following configuration: - -#enum(tight: false, - [ -The drogue chute is deployed by a pyrotechnic charge connected to #gls("pyro", cap: false) Channel 1, which must be turned on (Fig. #xref("fig:ExampleSimpleEvents")). -], - [ -The expected time to #gls("apogee", cap: false) is 15 seconds and is used for a backup timer (Fig. #xref("fig:ExampleSimpleTimers")). -], - [ -The main chute is deployed by a pyrotechnic charge connected to #gls("pyro", cap: false) Channel 2, which must be turned on (Fig. #xref("fig:ExampleSimpleEvents")). No timer is configured for main-chute deployment. -], - [ -The liftoff acceleration is simulated to be 70 $m/s^2$ (Fig. #xref("fig:ExampleSimpleConfig")). -] -) += Example Configurations -Configure these settings on the flight computer, then connect the battery, switch, and pyrotechnic charges to Pyro Channels 1 and 2. The completed CATS Vega setup should match Fig. #xref("fig:HWsimpleExample"). +#metadata(none) These examples show how hardware, flight events, actions, and timers fit together. Adapt all thresholds, deployment altitudes, delays, and output settings to the actual rocket and recovery system. -#cats-figure(image("../images/Examples/HWSimpleExample.png", width: 100%), caption: [CATS Vega with a battery, switch, Pyro 1 and Pyro 2 connected.]) +#warning[ +*Warning:* The values below are examples, not flight-ready recommendations. Verify the complete configuration in *Preflight* and test every recovery mechanism safely before flight. +] -#cats-figure( - stack(dir: ttb, spacing: 8pt, - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_simple_Config.png", width: 100%), [Configuration Tab (simple example).], "a") ]]], - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_simple_Events.jpg", width: 100%), [Event Tab (simple example).], "b") ]]], - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_simple_Timers.jpg", width: 100%), [Timer Tab (simple example).], "c") ]]] - ), - caption: [Configurator screenshots for the simple example configuration.], +== Simple Dual-Deployment Example + +This example uses a pyrotechnic charge on Pyro Channel 1 for the drogue parachute and a second charge on Pyro Channel 2 for the main parachute. + +#cats-table( + table( + columns: (0.24fr, 0.28fr, 0.48fr,), + inset: (x: 4pt, y: 4.5pt), + align: (x, y) => left + top, + stroke: 0.35pt + luma(45%), + fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, + [Area], [Example value], [Purpose], + [Configuration], [Liftoff threshold: 40 $m/s^2$], [Detect liftoff after the configured acceleration is sustained.], + [Events & Timers], [Apogee → Pyro 1 ON], [Deploy the drogue parachute at detected apogee.], + [Events & Timers], [Main Deployment → Pyro 2 ON], [Deploy the main parachute below the configured main altitude.], + [Events & Timers], [Timer: Liftoff → Apogee after 15 s], [Provide a time-based backup for the apogee event.], + table.hline(y: 1, stroke: 0.5pt + black) +), + caption: [Simple dual-deployment example], continued: false, -) - -#pagebreak() - -== Advanced Example Configuration - -For the advanced example, assume the following configuration: - -#enum(tight: false, - [ -The drogue chute is deployed by a solenoid valve connected to #gls("pyro", cap: false) Channel 1. The channel must be turned on for two seconds and then turned off (Fig. #xref("fig:ExampleAdvancedEvents")). -], - [ -The expected time to #gls("apogee", cap: false) is 45 seconds and is used for a backup timer (Fig. #xref("fig:ExampleAdvancedTimers")). -], - [ -The main parachute is deployed by Servo Channel 1. Its initial position is 15 degrees, and the deployment position is 90 degrees (Fig. #xref("fig:ExampleAdvancedConfig"), Fig. #xref("fig:ExampleAdvancedEvents")). -], - [ -No main parachute backup timer is used (Fig. #xref("fig:ExampleAdvancedTimers")). -], - [ -The main parachute should be opened at 350 $m$ (Fig. #xref("fig:ExampleAdvancedConfig")). -], - [ -The liftoff acceleration is simulated to be 60 $m/s^2$ (Fig. #xref("fig:ExampleAdvancedConfig")). -], - [ -A camera is connected to #gls("pyro", cap: false) Channel 2. It turns on at liftoff and off at touchdown (Fig. #xref("fig:ExampleAdvancedEvents")). -], - [ -The low-level #gls("I/O", cap: false) is turned on at burnout (Fig. #xref("fig:ExampleAdvancedEvents")). -] -) + breakable: true, +) + +Connect the battery and switch, then connect the deployment circuits to Pyro Channels 1 and 2 as shown below. Keep the charges disconnected while checking continuity and event behavior. + +#cats-figure(doc-image("Examples/HWSimpleExample.png", width: 100%), caption: [CATS Vega with a battery, switch, Pyro 1 and Pyro 2 connected.]) + +In *Preflight*, verify the main-deployment altitude, liftoff threshold, timer, event sequence, and both pyro actions. Use the procedure in Chapter #xref("sec:Testing") to test the configuration with safe substitutes before connecting energetic devices. + +== Advanced Recovery Example + +This example adds timed actions, a servo-deployed main parachute, a camera, and a low-level output. It illustrates the available building blocks; it is not a recommended configuration for a specific vehicle. + +#cats-table( + table( + columns: (0.25fr, 0.32fr, 0.43fr,), + inset: (x: 4pt, y: 4.5pt), + align: (x, y) => left + top, + stroke: 0.35pt + luma(45%), + fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, + [Area], [Example value], [Purpose], + [Configuration], [Liftoff threshold: 40 $m/s^2$], [Detect liftoff.], + [Configuration], [Main altitude: 350 m], [Trigger the Main Deployment event below 350 m during descent.], + [Configuration], [Servo 1 initial position: mechanism closed], [Hold the main-deployment mechanism in its safe initial position. Determine the actual value on the bench.], + [Events & Timers], [Apogee → Pyro 1 ON; delay 2 s; Pyro 1 OFF], [Operate a solenoid valve for two seconds.], + [Events & Timers], [Main Deployment → Servo 1 deployed position], [Open the main-deployment mechanism. Determine the deployed value on the bench.], + [Events & Timers], [Liftoff → Pyro 2 ON; Touchdown → Pyro 2 OFF], [Control an externally powered camera through a suitable interface.], + [Events & Timers], [Burnout → I/O ON], [Assert the low-level output at burnout.], + [Events & Timers], [Timer: Liftoff → Apogee after 45 s], [Provide a time-based backup for the apogee event.], + table.hline(y: 1, stroke: 0.5pt + black) +), + caption: [Advanced recovery example], + continued: false, + breakable: true, +) -Configure these settings on the flight computer, then connect the battery, switch, solenoid valve to #gls("pyro", cap: false) Channel 1, camera to #gls("pyro", cap: false) Channel 2, and #gls("servo", cap: false) to #gls("servo", cap: true) Channel 1. The completed CATS Vega setup should match Fig. #xref("fig:HWadvancedExample"). +Connect the battery and switch, the solenoid-valve interface to Pyro Channel 1, the camera interface to Pyro Channel 2, and the main-deployment mechanism to Servo Channel 1 as shown below. Observe the electrical limits in Section #xref("sec:VegaHW") and use external drivers where the load requires them. -#cats-figure(image("../images/Examples/HWAdvancedExample.png", width: 100%), caption: [CATS Vega with a battery, switch, solenoid valve, camera and servo connected.]) +#cats-figure(doc-image("Examples/HWAdvancedExample.png", width: 100%), caption: [CATS Vega with a battery, switch, solenoid valve, camera, and servo connected.]) -#cats-figure( - stack(dir: ttb, spacing: 8pt, - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_advanced_config.png", width: 100%), [Configuration Tab (advanced example).], "a") ]]], - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_advanced_events.jpg", width: 100%), [Event Tab (advanced example).], "b") ]]], - [#align(center)[#block(width: 75%)[#subfigure(image("../images/Examples/Config_advanced_timers.jpg", width: 100%), [Timer Tab (advanced example).], "c") ]]] - ), - caption: [Configurator screenshots for the advanced example configuration.], - continued: false, -) +Before flight, use *Preflight* to inspect the complete timeline, including delayed actions and timer-triggered events. Test each event individually in testing mode, then disable testing mode, reboot the Vega, and run Preflight again. #pagebreak() diff --git a/docs/Chapters/6_Testing.typ b/docs/Chapters/6_Testing.typ index 412b5c07..54b12256 100644 --- a/docs/Chapters/6_Testing.typ +++ b/docs/Chapters/6_Testing.typ @@ -4,76 +4,77 @@ = Testing -#metadata(none) This section explains how to run tests with the CATS System. +#metadata(none) Testing mode lets you trigger the Vega's configured events from a Ground Station while the system is secured on the bench. -== Working Principle +== What Testing Mode Does -The testing mode of the Vega flight computer works only with a ground station. Once the flight computer is in this mode all processing of information is disabled. This means that if the flight computer is flown while in testing mode, make sure you bring a shovel with you since you will need it to recover your rocket.#linebreak() Once the flight computer is in testing mode, a beeping sound is emitted, signaling that the computer is indeed in testing. A command from the ground station needs then to be set to arm the flight computer. When the flight computer is armed, events can be executed from the ground station.#linebreak() +Testing mode stops normal flight-state processing. After the Vega and Ground Station enter armed testing mode, the Ground Station can trigger any configured event. Every action assigned to that event is executed, including pyrotechnic, servo, low-level I/O, recorder, and delayed actions. + +#warning[ +*Warning:* Treat every configured output as live. Remove motors and energetic charges until you intentionally test that output, secure the hardware, and keep people clear of all deployment mechanisms. Never fly in testing mode. +] #note[ -*Note:* Unlike during flight, events can be triggered several times without needing to reboot the system. +*Note:* Unlike during flight, an event can be triggered repeatedly without rebooting. The Vega leaves armed testing mode if the telemetry link is lost. ] -By design, the testing mode only enables triggering events and not actions so that the user can verify that they added the correct configuration to the flight computer. +== Before You Start -== Enabling the Testing Mode +#list(tight: false, + [Secure the Vega, battery, Ground Station, and every connected mechanism on a suitable test bench.], + [Disconnect pyrotechnic charges, motors, and other energetic devices unless testing them is the specific purpose of the procedure.], + [In the Configurator, review *Events & Timers* and confirm every action that will run for each event.], + [Open *Preflight* and resolve every reported configuration or connection problem.], + [Confirm that the Vega and Ground Station use the same receiver mode, link phrase, and testing phrase.] +) -To enable the testing mode, follow these steps: +== Enabling and Using Testing Mode #enum(tight: false, - [ -Connect your CATS Vega to your computer, start the Configurator, and connect to the flight computer. -], - [ -On the Configurator's Home screen, enable Testing Mode. -], - [ -Set a testing phrase. -], - [ -Reboot the flight computer. If the flight computer is not restarted, the testing mode is not activated. -], - [ -The flight computer should emit the "Testing" beeping pattern. See Section #xref("sec:BeepingPatterns") for more information. -], - [ -Turn on your Ground Station. -], - [ -Make sure that the link phrase and testing phrase match those configured on the flight computer. -], - [ -Open the Testing menu on the Ground Station. - -#cats-figure(image("../images/Testing/GroundStation_MainMenu.jpg", width: 70%), caption: [Ground Station Main Menu.]) -], - [ -Read the disclaimer carefully and arm testing mode. *Attention:* After this step, executing events will trigger the connected mechanisms. Follow all safety guidelines. - -#cats-figure(image("../images/Testing/GroundStation_Arm_Testing_Mode.jpg", width: 70%), caption: [Arming the test mode.]) -], - [ -A pop-up indicates that testing mode is being activated. Wait until it disappears. - -#cats-figure(image("../images/Testing/GroundStation_Wait_Testing_Mode.jpg", width: 70%), caption: [Waiting for testing mode to activate.]) -], - [ -The flight computer should emit the "Armed Testing" beeping pattern. See Section #xref("sec:BeepingPatterns") for more information. -], - [ -Select the event that you want to trigger. - -#cats-figure(image("../images/Testing/GroundStation_Event_Menu.jpg", width: 70%), caption: [Selection of the Event to be triggered.]) -], - [ -Select the event and confirm. - -#cats-figure(image("../images/Testing/GroundStation_Trigger_Event.jpg", width: 70%), caption: [Confirming to trigger the desired Event.]) -] + [Connect the Vega to the computer and open the Configurator. The Configurator connects automatically when exactly one compatible Vega is available; otherwise, select it manually.], + [Open *Configuration*, enable *Testing Mode*, and set a testing phrase. Save the configuration.], + [Reboot the Vega. Testing mode does not become active until after the reboot.], + [Confirm that the Vega emits the *Testing* beeping pattern described in Section #xref("sec:BeepingPatterns").], + [Turn on the Ground Station. In *Settings* → *Telemetry*, select the matching receiver mode and set *Link Phrase 1* and *Test Phrase* to the values configured on the Vega.], + [Open *Testing* on the Ground Station. Read the safety notice, press the A button to continue, and wait for the Ground Station to arm the Vega.], + [Confirm that the Vega emits the *Armed Testing* beeping pattern.], + [Select an event, review the confirmation screen, and confirm only when the test area is clear. Observe every configured output and delayed action.], + [Repeat only the checks required for the test. If the telemetry link is lost, return to the Testing menu and arm the system again.] +) + +#cats-figure( + figure-stack( + spacing: 14pt, + responsive-split( + [#subfigure(doc-image("Testing/GS_Testing_Safety.png", width: 100%, outline: true, alt: "Ground Station testing-mode safety notice"), [Read the complete safety notice.], "a")], + [#subfigure(doc-image("Testing/GS_Testing_ReadyToStart.png", width: 100%, outline: true, alt: "Ground Station testing-mode arm confirmation"), [Continue only when the connected Vega is in testing mode.], "b")], + columns: (45%, 1fr, 45%), + ), + responsive-split( + [#subfigure(doc-image("Testing/GS_Testing_Starting.png", width: 100%, outline: true, alt: "Ground Station waiting for testing mode to start"), [Wait while the Ground Station arms the Vega.], "c")], + [#subfigure(doc-image("Testing/GS_Testing_Events.png", width: 100%, outline: true, alt: "Ground Station testing event selection screen"), [Select the configured event to test.], "d")], + columns: (45%, 1fr, 45%), + ), + ), + caption: [Entering testing mode and selecting an event], +) + +#cats-figure( + doc-image("Testing/GS_Testing_Confirm.png", width: 60%, outline: true, alt: "Ground Station confirmation before triggering a test event"), + caption: [Final confirmation before triggering the selected event], +) + +== Returning to Flight Configuration + +#enum(tight: false, + [Exit *Testing* on the Ground Station.], + [Reconnect the Vega to the Configurator, disable *Testing Mode*, and save the configuration.], + [Reboot the Vega and confirm that the Testing beep pattern is no longer emitted.], + [Run *Preflight* again before installing energetic devices or preparing the rocket for flight.] ) #warning[ -*Warning:* Testing mode enables manual triggering of events and corresponding actions associated with them. This feature should only be used for testing purposes and never during flight or other non-controlled activities. CATS GmbH is not responsible for any potential injuries or material damage caused by manual operation of the CATS System. +*Warning:* Testing mode manually executes the actions assigned to the selected event. CATS GmbH is not responsible for injuries or material damage caused by unsafe manual operation of the CATS System. ] #pagebreak() diff --git a/docs/Chapters/7_AdvancedInformation.typ b/docs/Chapters/7_AdvancedInformation.typ index 103cfa27..5b002eba 100644 --- a/docs/Chapters/7_AdvancedInformation.typ +++ b/docs/Chapters/7_AdvancedInformation.typ @@ -8,7 +8,7 @@ This section provides a brief overview of the software architecture. It is intended for advanced users with some programming experience; understanding it is not required to use the flight computer.#linebreak() The software is implemented in C++ and uses #gls("FreeRTOS", cap: false) as its foundation. The hardware is initialized first, after which the tasks are started. Figure #xref("fig:SoftwareOverview") shows the running tasks. -#cats-figure(image("../images/Working Principle/Software_Overview_Vega.png", width: 100%), caption: [Illustration of the different FreeRTOS tasks interacting with each other and the hardware. The black circle 'Settings' is just a memory region that is being accessed by different tasks.]) +#cats-figure(doc-image("Working Principle/Software_Overview_Vega.png", width: 100%), caption: [Illustration of the different FreeRTOS tasks interacting with each other and the hardware. The black circle 'Settings' is just a memory region that is being accessed by different tasks.]) The following list briefly describes each task. @@ -47,13 +47,17 @@ The following list briefly describes each task. == Telemetry -The telemetry system uses 2.4 GHz LoRa and #gls("fhss", cap: false) (Frequency-Hopping Spread Spectrum). #gls("fhss", cap: false) makes transmissions more resistant to interference and more difficult to intercept. It also allows more devices to use the same frequency band with little or no effect on link quality. #linebreak()#linebreak()#v(1.8pt) +The telemetry system uses 2.4 GHz LoRa and #gls("fhss", cap: false) (Frequency-Hopping Spread Spectrum). #gls("fhss", cap: false) makes transmissions more resistant to interference and more difficult to intercept. It also allows more devices to use the same frequency band with little or no effect on link quality. -*Hopping Pattern*#linebreak()#v(-1.8pt) The link phrase defines the hopping pattern. It is hashed with a #gls("crc", cap: false)-32 algorithm, and the resulting value seeds a pseudo-random number generator. The generator runs 20 times to define the hopping pattern. As a result, a given link phrase always produces the same pattern. The transmitter and receiver must use the same link phrase to communicate.#linebreak()#linebreak()#v(1.8pt) +#heading(level: 3, numbering: none, outlined: false)[Hopping Pattern] -#cats-figure(image("../images/Working Principle/fhss.png", width: 100%), caption: [#gls("fhss", cap: false) transmission example]) +The link phrase defines the hopping pattern. It is hashed with a #gls("crc", cap: false)-32 algorithm, and the resulting value seeds a pseudo-random number generator. The generator runs 20 times to define the hopping pattern. As a result, a given link phrase always produces the same pattern. The transmitter and receiver must use the same link phrase to communicate. -*Synchronization*#linebreak()#v(-1.8pt) The receiver waits on the first frequency until it receives a synchronization packet. This packet contains the link #gls("crc", cap: false), which identifies the transmission source. If the remote #gls("crc", cap: false) matches the local value, the receiver hops to the next frequency and waits for data. Each data packet contains a checksum for validating its contents. The receiver measures the interval between packets and hops to the next frequency when a packet is not received within the estimated interval. It can perform 30 hops without receiving a packet before synchronization is lost. If the connection is lost, the receiver returns to the first frequency. +#cats-figure(doc-image("Working Principle/fhss.png", width: 100%), caption: [#gls("fhss", cap: false) transmission example]) + +#heading(level: 3, numbering: none, outlined: false)[Synchronization] + +The receiver waits on the first frequency until it receives a synchronization packet. This packet contains the link #gls("crc", cap: false), which identifies the transmission source. If the remote #gls("crc", cap: false) matches the local value, the receiver hops to the next frequency and waits for data. Each data packet contains a checksum for validating its contents. The receiver measures the interval between packets and hops to the next frequency when a packet is not received within the estimated interval. It can perform 30 hops without receiving a packet before synchronization is lost. If the connection is lost, the receiver returns to the first frequency. #pagebreak() @@ -61,13 +65,19 @@ The telemetry system uses 2.4 GHz LoRa and #gls("fhss", cap: false) (Frequency #metadata(none) State estimation calculates the rocket's velocity and altitude from barometric pressure and linear acceleration in the $z$ direction.#linebreak() -*Calibration of Sensors*#linebreak()#v(-1.8pt) Linear acceleration is calibrated when the system enters the #gls("Ready", cap: false) state. This allows the flight computer to be mounted in any orientation. The gravity vector is used to calculate the up direction, which is then used throughout the flight. +#heading(level: 3, numbering: none, outlined: false)[Calibration of Sensors] + +Linear acceleration is calibrated when the system enters the #gls("Ready", cap: false) state. This allows the flight computer to be mounted in any orientation. The gravity vector is used to calculate the up direction, which is then used throughout the flight. #warning[ *Warning:* Power up the flight computer only after the rocket is upright on the launch pad. To prevent repeated transitions into and out of the #gls("Ready", cap: false) state, calibration is performed only once, as soon as no motion is detected after startup. ] -During #gls("Calibrating", cap: false) and #gls("Ready", cap: false), the current altitude above sea level is continuously estimated. Altitude above ground level, the value used during flight, is calculated from the altitude above sea level. This calculation assumes that barometric pressure changes very slowly. When #gls("liftoff", cap: false) is detected, the altitude above sea level is fixed, and only the altitude above ground level is updated. *Kalman Filter*#linebreak()#v(-1.8pt) A #gls("Kalman Filter", cap: false) estimates altitude and velocity from the calibrated values. Its derivation is described below. We define the state and noise as +During #gls("Calibrating", cap: false) and #gls("Ready", cap: false), the current altitude above sea level is continuously estimated. Altitude above ground level, the value used during flight, is calculated from the altitude above sea level. This calculation assumes that barometric pressure changes very slowly. When #gls("liftoff", cap: false) is detected, the altitude above sea level is fixed, and only the altitude above ground level is updated. + +#heading(level: 3, numbering: none, outlined: false)[Kalman Filter] + +A #gls("Kalman Filter", cap: false) estimates altitude and velocity from the calibrated values. Its derivation is described below. We define the state and noise as $ x(t) = mat(h(t); v(t); a_(o)(t)) quad v = mat(v_1; v_2) $ @@ -101,7 +111,15 @@ The measurement-noise matrix becomes a scalar: $ R(k) = R_("height") $ -The standard Kalman-filter equations can then propagate the state. #linebreak()#v(-1.8pt) *Gain Scheduling* #linebreak()#v(-1.8pt) Gain scheduling reduces reliance on the barometer during high-velocity flight, because barometric measurements can behave unpredictably in the transonic regime. #linebreak() At #gls("liftoff", cap: false) and while the rocket is moving quickly, the accelerometer is weighted more heavily when estimating altitude and velocity. At lower velocities, barometric pressure is weighted more heavily because accelerometer drift affects the estimate. As the rocket arcs over, the quality of the accelerometer measurement also decreases.#linebreak() Two variables control the relative trust in the sensors: $Q_("acc")$ and $R_("height")$. In the algorithm, $Q_("acc")$ remains constant, while $R_("height")$ changes during flight.#linebreak() The conditions for changing $R_("height")$ are shown below. +The standard Kalman-filter equations can then propagate the state. + +#heading(level: 3, numbering: none, outlined: false)[Gain Scheduling] + +Gain scheduling reduces reliance on the barometer during high-velocity flight, because barometric measurements can behave unpredictably in the transonic regime. + +At #gls("liftoff", cap: false) and while the rocket is moving quickly, the accelerometer is weighted more heavily when estimating altitude and velocity. At lower velocities, barometric pressure is weighted more heavily because accelerometer drift affects the estimate. As the rocket arcs over, the quality of the accelerometer measurement also decreases. + +Two variables control the relative trust in the sensors: $Q_("acc")$ and $R_("height")$. In the algorithm, $Q_("acc")$ remains constant, while $R_("height")$ changes during flight. The conditions for changing $R_("height")$ are shown below. $ R_("height") = cases(R_("initial"), & "for state = MOVING or IDLE", R_("max"), & "for state = LIFTOFF", R_("max") dot f(v), & "for state = COASTING", R_("initial"), & "otherwise") $ @@ -132,9 +150,9 @@ For more information about the visualizer script, run: #pagebreak() -== Description of the CLI +== Common CLI Commands -#metadata(none) This section describes all commands available in the CLI. To access the CLI, connect the board to your computer, connect through the Configurator, and open the CLI tab. #linebreak() In the list below, square brackets #text(font: "DejaVu Sans Mono", size: 0.9em)[\[ \]] indicate an optional argument, while angle brackets \< \> identify a parameter name.#linebreak() After changing the configuration through the CLI, verify it with the #text(font: "DejaVu Sans Mono", size: 0.9em)[config] command. +#metadata(none) The CLI is intended for advanced inspection, recovery, and configuration. To access it, connect the Vega through the Configurator and open *CLI*. The commands and parameters below are the most useful ones; run #text(font: "DejaVu Sans Mono", size: 0.9em)[help] for the authoritative list provided by the connected firmware. Square brackets #text(font: "DejaVu Sans Mono", size: 0.9em)[\[ \]] indicate an optional argument, while angle brackets \< \> identify a parameter name.#linebreak() After changing configuration values, run #text(font: "DejaVu Sans Mono", size: 0.9em)[save] and verify the result with #text(font: "DejaVu Sans Mono", size: 0.9em)[config]. #cats-table( table( @@ -145,7 +163,7 @@ For more information about the visualizer script, run: fill: (x, y) => if calc.even(y) { luma(90%) } else { white }, [#text(font: "DejaVu Sans Mono", size: 0.9em)[bl]], [Put the board into DFU mode], - [Needed for software updates (refer to Section #xref("sec:softwareupdates"))], + [For advanced recovery. Normal firmware updates use the Configurator workflow in Chapter #xref("sec:FirmwareUpdates").], [#text(font: "DejaVu Sans Mono", size: 0.9em)[cd]], [Change the current working directory], [], @@ -170,16 +188,16 @@ For more information about the visualizer script, run: [#text(font: "DejaVu Sans Mono", size: 0.9em)[flash\_stop\_write]], [Stop writing to flash], [For testing purposes only; do not use], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[flight\_dump \< flight\_id\>]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[flight\_dump \]], [Print a specific flight in binary format], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[flight\_parse \< flight\_id\>]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[flight\_parse \]], [Print a specific flight in a human-readable format], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[get \[\< variable\>\]]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[get \[command\_name\]]], [Get a variable value, described in Table #xref("tab:CLICommandsSetGet")], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[help \[\< command name\>\]]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[help \[search string\]]], [Display all commands with a description], [], [#text(font: "DejaVu Sans Mono", size: 0.9em)[lfs\_format]], @@ -188,7 +206,7 @@ For more information about the visualizer script, run: [#text(font: "DejaVu Sans Mono", size: 0.9em)[log\_enable]], [Enable log output on the terminal], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[ls \[\< path\>\]]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[ls]], [List all files in the current working directory], [], [#text(font: "DejaVu Sans Mono", size: 0.9em)[reboot]], @@ -197,16 +215,16 @@ For more information about the visualizer script, run: [#text(font: "DejaVu Sans Mono", size: 0.9em)[rec\_info]], [Get information about flash usage], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[rm \[\< path\>\]]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[rm \]], [Remove a file], [], [#text(font: "DejaVu Sans Mono", size: 0.9em)[save]], [Save flight configuration], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[set \[\< variable\> =\< value\>\]]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[set \[\=\\]]], [Set a variable, described in Table #xref("tab:CLICommandsSetGet")], [], - [#text(font: "DejaVu Sans Mono", size: 0.9em)[stats \< flight\_id\>]], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[stats \]], [Print flight statistics], [], [#text(font: "DejaVu Sans Mono", size: 0.9em)[status]], @@ -216,14 +234,12 @@ For more information about the visualizer script, run: [Show the firmware version], [] ), - caption: [Exhaustive List of #gls("CLI", cap: false) Commands], + caption: [Common #gls("CLI", cap: false) commands], continued: false, breakable: true, ) -#pagebreak() - -#heading(level: 3, outlined: false)[Get and Set Commands] +#heading(level: 3, outlined: false)[Common Configuration Parameters] The variables below can be read with the #text(font: "DejaVu Sans Mono", size: 0.9em)[get] command or changed with the #text(font: "DejaVu Sans Mono", size: 0.9em)[set] command. Changes are saved to the flight computer's configuration only after the #text(font: "DejaVu Sans Mono", size: 0.9em)[save] command is run. @@ -282,6 +298,9 @@ The variables below can be read with the #text(font: "DejaVu Sans Mono", size: 0 [#text(font: "DejaVu Sans Mono", size: 0.9em)[ev\_ready]], [Set the actions associated with the ready event], [Do not use!], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[ev\_liftoff]], + [Set the actions associated with the liftoff event], + [Prefer the Configurator's Events & Timers page.], [#text(font: "DejaVu Sans Mono", size: 0.9em)[ev\_burnout]], [Set the actions associated with the burnout event], [Do not use!], @@ -315,6 +334,9 @@ The variables below can be read with the #text(font: "DejaVu Sans Mono", size: 0 [#text(font: "DejaVu Sans Mono", size: 0.9em)[tele\_power\_level]], [Set the telemetry power level], [], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[tele\_enable]], + [Enable or disable telemetry], + [], [#text(font: "DejaVu Sans Mono", size: 0.9em)[tele\_adaptive\_power]], [Enable or disable adaptive power for the telemetry power level], [Adaptive power mode boosts output power to maximum when the flight computer is in _THRUSTING_ mode and returns it to the user-set value when _TOUCHDOWN_ is registered.], @@ -329,9 +351,12 @@ The variables below can be read with the #text(font: "DejaVu Sans Mono", size: 0 [A bit mask corresponding to the #link("https://github.com/catsystems/cats-embedded/blob/674192f757e7b1cd11fc023cafc6ea9dcf132f5f/flight_computer/src/flash/recorder.hpp#L35")[#text(font: "DejaVu Sans Mono", size: 0.9em)[rec\_entry\_type\_e]] enum], [#text(font: "DejaVu Sans Mono", size: 0.9em)[rec\_speed]], [Set the desired sampling period for recording], - [] + [], + [#text(font: "DejaVu Sans Mono", size: 0.9em)[test\_mode]], + [Enable or disable testing mode], + [A reboot is required after saving the change.] ), - caption: [Exhaustive List of parameters used in the #text(font: "DejaVu Sans Mono", size: 0.9em)[get] and #text(font: "DejaVu Sans Mono", size: 0.9em)[set] Commands], + caption: [Common parameters used with the #text(font: "DejaVu Sans Mono", size: 0.9em)[get] and #text(font: "DejaVu Sans Mono", size: 0.9em)[set] commands], continued: false, breakable: true, ) diff --git a/docs/Chapters/8_FAQ.typ b/docs/Chapters/8_FAQ.typ index c3d75a2f..8f5abdcc 100644 --- a/docs/Chapters/8_FAQ.typ +++ b/docs/Chapters/8_FAQ.typ @@ -1,11 +1,21 @@ #import "../styles.typ": * -= FAQ += FAQ and Troubleshooting #metadata(none) -*My testing mode doesn't work*#linebreak()#v(-1.8pt) To enable testing mode, make sure that you have enabled testing mode on the flight computer through the Configurator and set a valid testing phrase. Otherwise, the flight computer will start in its default mode and will not accept testing commands from the Ground Station.#linebreak()#linebreak()#v(1.8pt) +*The Configurator does not find my Vega*#linebreak()#v(-1.8pt) Use a USB data cable and connect the Vega directly to the computer. If more than one compatible device is connected, select the intended device manually. Use the refresh button in the device selector after reconnecting the cable. On Windows, also check whether another application has opened the same serial port.#linebreak()#linebreak()#v(1.8pt) -*The Configurator sometimes doesn't apply my settings*#linebreak()#v(-1.8pt) Connect the flight computer directly to your computer without a USB hub. If that does not help, contact us on Discord or submit an issue on GitHub.#linebreak()#linebreak()#v(1.8pt) +*My configuration changes disappear after reconnecting*#linebreak()#v(-1.8pt) Select *Save* before disconnecting or rebooting the Vega. After saving, use *Refresh* or reconnect and confirm that the stored values match the intended configuration. Run *Preflight* before flight.#linebreak()#linebreak()#v(1.8pt) -*To be extended with user feedback...*#linebreak()#linebreak()#v(1.8pt) +*The Ground Station does not receive telemetry*#linebreak()#v(-1.8pt) Confirm that telemetry is enabled on the Vega, both devices have antennas attached, and the Ground Station receiver mode and link phrase match the Vega configuration. In Single mode, Link Phrase 1 is used by both receivers; in Dual mode, each receiver has its own phrase. Check the Ground Station's *Firmware Versions* page if only one receiver behaves unexpectedly.#linebreak()#linebreak()#v(1.8pt) + +*Testing mode does not arm*#linebreak()#v(-1.8pt) Enable testing mode and set a valid testing phrase in the Configurator, save the configuration, and reboot the Vega. Set the same Test Phrase and receiver mode on the Ground Station. The Vega must emit the Testing beep pattern before the Ground Station can arm it. See Chapter #xref("sec:Testing") for the complete safety procedure.#linebreak()#linebreak()#v(1.8pt) + +*A flight or Ground Station log is missing*#linebreak()#v(-1.8pt) Vega flight logs can be opened from the Configurator's *Flight Logs* page, including logs still stored onboard. Ground Station logs are exposed on the *CATS GS* USB drive; finalize an active log before copying it, and use *Settings* → *System* → *USB Drive* before disconnecting the cable.#linebreak()#linebreak()#v(1.8pt) + +*A firmware update was interrupted*#linebreak()#v(-1.8pt) Reconnect the device and start the update again using the recovery procedure in Chapter #xref("sec:FirmwareUpdates"). After any update, reconnect and verify the reported version before using the device. Normal Vega firmware installation from the Configurator is supported on Windows.#linebreak()#linebreak()#v(1.8pt) + +*GNSS position is unavailable or inaccurate*#linebreak()#v(-1.8pt) Move the Vega and Ground Station outdoors with a clear view of the sky, keep antennas away from large conductive objects, and allow time for a fix. Do not rely on the last displayed coordinates until the Ground Station shows a current fix.#linebreak()#linebreak()#v(1.8pt) + +If the problem remains, collect the device and firmware versions, describe the exact steps taken, and contact us on our #link("https://discord.gg/r7ErmSNvsy")[Discord server] or open an issue in the relevant #link("https://github.com/catsystems")[CATS repository]. diff --git a/docs/Chapters/FirmwareUpdates.typ b/docs/Chapters/FirmwareUpdates.typ new file mode 100644 index 00000000..c9d69d3e --- /dev/null +++ b/docs/Chapters/FirmwareUpdates.typ @@ -0,0 +1,147 @@ +#import "../styles.typ": * + += Firmware Updates + +#metadata(none) The Configurator installs official stable firmware for the CATS Vega and Ground Station. It also prepares the firmware file that the Ground Station uses to update both of its radio receivers. Use the Firmware Updates page instead of downloading files and selecting programming tools manually. + +Normal firmware installation is supported on Windows. On Linux and macOS, the Configurator can check connected devices and releases, but the standard release keeps flashing disabled until those USB workflows have completed hardware acceptance. + +== Before Updating + +#enum(tight: false, + [ +Install the latest Configurator from the #link("https://github.com/catsystems/cats-configurator/releases/")[Configurator releases page]#source-note("https://github.com/catsystems/cats-configurator/releases"). The Firmware Updates page updates connected CATS devices; it does not update the Configurator application itself. +], + [ +Save or discard any unsaved configuration changes. Firmware installation is disabled while the Configurator contains unsaved changes. +], + [ +Connect only the device that you intend to update. Disconnect deployment charges and place the Vega safely on the bench. Stop Ground Station tracking and recording, and close any files opened from its USB drive. +], + [ +Keep the device powered and connected until the Configurator or Ground Station reports that verification has completed. +] +) + +#warning[ +*Warning:* Never update a Vega with deployment charges or other energetic outputs connected. Do not reset, unplug, or power off a device while firmware is being written or verified. +] + +== Updating the Configurator + +Download the current installer from the Configurator releases page, close the running Configurator, and run the installer. After installation, open the Configurator and confirm the expected *App version* in the footer. + +#cats-figure( + doc-image("How To Use/Configurator/Configurator_Firmware_Updates.png", width: 100%, alt: "Configurator Firmware Updates page after checking connected devices and official releases"), + caption: [Configurator Firmware Updates page after a successful device and release check], +) + +== Updating the CATS Vega + +#enum(tight: false, + [ +Connect the Vega by USB, open *Firmware Updates*, and select *Check devices & releases*. +], + [ +In the Vega panel, verify the detected device, installed version, and available version. Select *Update Vega*. +], + [ +Confirm that deployment charges are disconnected. If the installed version is unknown or the same version is being reinstalled, acknowledge the additional confirmation shown by the Configurator. +], + [ +Select *Start update*. The Configurator downloads and validates the official image, moves the Vega into its native USB DFU bootloader, erases and writes the application, reads it back for verification, and starts the new firmware. +], + [ +Leave USB connected while the Vega reconnects. The update is complete only after the Configurator verifies the running firmware version. +] +) + +The Configurator prevents cancellation after the device starts transitioning into its bootloader. If the application reports a failed verification or reconnect step, leave the Vega connected and use the offered retry action. STM32CubeProgrammer and an ST-Link debugger are service and recovery tools, not part of the normal update procedure. + +== Updating the Ground Station + +#enum(tight: false, + [ +Connect the Ground Station through its normal USB port. Stop tracking and recording, and close all files on the `CATS GS` drive. +], + [ +Open *Firmware Updates*, select *Check devices & releases*, and verify the Ground Station detected from its `version.json` information. +], + [ +Select *Update Ground Station*, confirm the safety prompt, and start the update. Keep the Ground Station connected while the Configurator enters TinyUF2, copies the official `.uf2` image, and waits for the application to return. +], + [ +The update is complete only when the Configurator reads a fresh `version.json` and reports the installed version. +] +) + +If automatic bootloader entry is unavailable, use *Settings* $arrow.r$ *System* $arrow.r$ *Update Firmware* $arrow.r$ *Ground Station* on the device. Then return to the Configurator, check devices again, and start or retry the update. Do not use a 1200-baud reset; on this hardware it enters the ESP32 ROM bootloader rather than the supported TinyUF2 update path. + +== Updating the Ground Station Radio Receivers + +The Configurator validates and copies the radio image, while the Ground Station performs the installation on both receiver modules. + +#enum(tight: false, + [ +Connect the normal `CATS GS` USB drive, open *Firmware Updates*, and select *Check devices & releases*. +], + [ +In the Ground Station radios panel, verify the detected drive and available version. Select *Prepare radio firmware* and confirm that tracking, recording, and file access have stopped. +], + [ +After preparation succeeds, close all files and safely eject the `CATS GS` drive from the computer. +], + [ +On the Ground Station, open *Settings* $arrow.r$ *System* $arrow.r$ *Update Firmware* $arrow.r$ *Radio Receivers*. +], + [ +Select the prepared `.bin` file from the `telemetry_firmware` directory and confirm the update. Keep the Ground Station powered while it updates and verifies both radios. +], + [ +Do not leave the update screen until it reports *Both radios verified* and shows the expected version for Link 1 and Link 2. +], + [ +Power-cycle the Ground Station, reconnect its normal USB drive, and select *Check devices & releases* in the Configurator to refresh all reported versions. +] +) + +#note[ +*Note:* A completed file-copy progress bar means only that the radio image was prepared. It does not mean that either receiver was updated. Installation and verification take place on the Ground Station. +] + +#warning[ +*Compatibility:* Telemetry receiver firmware 1.2.0 is the first version that can enter this updater. Receivers running version 1.1.3 or earlier require a one-time ST-Link installation of version 1.2.0 or newer. If a receiver cannot enter the updater, the Ground Station stops before erasing or writing it. Restart the Ground Station before another update attempt. +] + +The following Ground Station screens show the complete on-device sequence. Filenames, versions, sizes, and checksums are examples; use the file and version prepared by your Configurator. + +#cats-figure( + figure-stack( + spacing: 16pt, + responsive-split( + [#subfigure(doc-image("How To Use/Software Update/Radio_Settings.png", width: 100%, outline: true), [Open Update Firmware from the System settings page.], "a")], + [#subfigure(doc-image("How To Use/Software Update/Radio_Receivers.png", width: 100%, outline: true), [Select Radio Receivers.], "b")], + columns: (45%, 1fr, 45%), + ), + responsive-split( + [#subfigure(doc-image("How To Use/Software Update/Radio_File.png", width: 100%, outline: true), [Select the prepared radio image.], "c")], + [#subfigure(doc-image("How To Use/Software Update/Radio_Confirm.png", width: 100%, outline: true), [Confirm the selected image and keep power connected.], "d")], + columns: (45%, 1fr, 45%), + ), + responsive-split( + [#subfigure(doc-image("How To Use/Software Update/Radio_Progress.png", width: 100%, outline: true), [Wait while each receiver is written and verified.], "e")], + [#subfigure(doc-image("How To Use/Software Update/Radio_Complete.png", width: 100%, outline: true), [Confirm that both radios were verified.], "f")], + columns: (45%, 1fr, 45%), + ), + ), + caption: [Ground Station radio-receiver update sequence], + continued: false, +) + +== Recovering an Interrupted Update + +Keep the device connected and follow the retry action shown by the Configurator. A Vega that remains in native DFU can be written and verified again. A Ground Station already in TinyUF2 can be checked again before retrying the validated update. If a radio update was interrupted, reopen the Ground Station's Radio Receivers update screen and run the prepared file again, then verify both reported versions. + +If a device cannot enter its supported bootloader or cannot be detected after the documented retries, disconnect all outputs and contact CATS support. Direct programming through STM32CubeProgrammer or an ST-Link debugger is reserved for service recovery and factory provisioning. + +#pagebreak() diff --git a/docs/Main.typ b/docs/Main.typ index ebfb7764..a1cc60cd 100644 --- a/docs/Main.typ +++ b/docs/Main.typ @@ -14,13 +14,16 @@ #show outline.entry.where(level: 1): it => block(above: 15pt, below: 2pt)[#strong(it)] #show outline.entry.where(level: 2): it => block(below: 1.2pt)[#it] #show outline.entry.where(level: 3): it => block(below: 0.8pt)[#it] +#align(right)[ + #text(size: 9pt, fill: luma(45%))[Last updated: #manual-last-updated] +] +#v(8pt) #block[ #set text(size: 10pt) #outline(title: [Contents], depth: 3, indent: auto) ] #pagebreak() -#include "Chapters/1_RevisionHistory.typ" #include "Chapters/Glossary.typ" #pagebreak() @@ -29,6 +32,7 @@ #include "Chapters/2_Introduction.typ" #include "Chapters/3_Vega.typ" #include "Chapters/4_GroundStation.typ" +#include "Chapters/FirmwareUpdates.typ" #include "Chapters/5_Example.typ" #include "Chapters/6_Testing.typ" #include "Chapters/7_AdvancedInformation.typ" diff --git a/docs/README.md b/docs/README.md index dcff48eb..e4ca7213 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,11 @@ This directory contains the Typst sources and required assets for the CATS User Install Typst 0.15.1, then run the following command from the `cats-embedded` repository root: ```powershell -typst compile --root docs --font-path docs/fonts --ignore-system-fonts docs/Main.typ "Cats User Manual.pdf" +node docs/build-manual.mjs ``` -`Main.typ` is the document entry point. Chapter sources are in `Chapters`, shared layout definitions are in `styles.typ`, and the locally vendored Roboto fonts are in `fonts`. Code snippets use Typst's embedded DejaVu Sans Mono, so the build does not depend on system fonts. +`Main.typ` is the PDF entry point and `Web.typ` is the single-page HTML entry point. Both import the same chapter sources. Shared, target-aware presentation helpers are in `styles.typ`, and the locally vendored Roboto fonts are in `fonts`. Code snippets use Typst's embedded DejaVu Sans Mono, so the build does not depend on system fonts. + +The generated outputs are `CATS User Manual.pdf` and `docs/generated/manual.html`. The HTML document loads its images lazily from the matching paths on `cats-embedded/main`, allowing `https://catsystems.io/manual` to follow newly merged documentation without rebuilding CATS Flights. + +Run `node docs/check-manual.mjs` after building to validate internal links, external image paths, semantic figures, MathML, and the no-script policy. CI rebuilds both outputs with Typst 0.15.1 and rejects stale generated files or any warning other than Typst's explicit experimental-HTML notice. diff --git a/docs/Web.typ b/docs/Web.typ new file mode 100644 index 00000000..470796a0 --- /dev/null +++ b/docs/Web.typ @@ -0,0 +1,39 @@ +#import "styles.typ": * + +#show pagebreak: it => none +#show v: it => none + +#html.elem("html", attrs: (lang: "en"))[ + #html.elem("head")[ + #html.elem("meta", attrs: (charset: "utf-8")) + #html.elem("meta", attrs: (name: "viewport", content: "width=device-width, initial-scale=1")) + #html.elem("meta", attrs: (name: "description", content: "CATS User Manual for the Vega flight computer and Ground Station.")) + #html.elem("link", attrs: (rel: "canonical", href: "https://catsystems.io/manual")) + #html.elem("title")[CATS User Manual] + ] + #html.elem("body")[ + #html.elem("nav", attrs: (class: "contents", aria-label: "Contents"))[ + #html.elem("h2")[Contents] + #outline(title: none, depth: 3) + ] + #html.elem("main")[ + #html.elem("article", attrs: (class: "manual-article"))[ + #html.elem("div", attrs: (class: "manual-title"))[ + #html.elem("h1")[CATS User Manual] + #html.elem("p")[Last updated: #manual-last-updated] + ] + #include "Chapters/Glossary.typ" + #include "Chapters/1.5_Disclaimer.typ" + #include "Chapters/1.6_RegulatoryInformation.typ" + #include "Chapters/2_Introduction.typ" + #include "Chapters/3_Vega.typ" + #include "Chapters/4_GroundStation.typ" + #include "Chapters/FirmwareUpdates.typ" + #include "Chapters/5_Example.typ" + #include "Chapters/6_Testing.typ" + #include "Chapters/7_AdvancedInformation.typ" + #include "Chapters/8_FAQ.typ" + ] + ] + ] +] diff --git a/docs/build-manual.mjs b/docs/build-manual.mjs new file mode 100644 index 00000000..5a8f22bd --- /dev/null +++ b/docs/build-manual.mjs @@ -0,0 +1,36 @@ +import { mkdirSync } from "node:fs"; +import { spawnSync } from "node:child_process"; + +const expectedHtmlWarning = [ + "warning: html export is under active development and incomplete", + " = hint: its behaviour may change at any time", + " = hint: do not rely on this feature for production use cases", + " = hint: see https://github.com/typst/typst/issues/5512 for more information", +].join("\n"); + +function typst(args, expectedWarning = "") { + const result = spawnSync("typst", args, { encoding: "utf8" }); + if (result.stdout) process.stdout.write(result.stdout); + if (result.status !== 0) { + if (result.stderr) process.stderr.write(result.stderr); + process.exit(result.status ?? 1); + } + + const warnings = result.stderr.trim().replaceAll("\r\n", "\n"); + if (warnings !== expectedWarning) { + console.error(warnings || "Unexpectedly missing Typst warning output."); + process.exit(1); + } +} + +const version = spawnSync("typst", ["--version"], { encoding: "utf8" }); +if (version.status !== 0 || !version.stdout.trim().startsWith("typst 0.15.1")) { + console.error(`CATS manuals require Typst 0.15.1; found: ${version.stdout.trim() || "unavailable"}`); + process.exit(1); +} + +mkdirSync("docs/generated", { recursive: true }); + +const common = ["--root", "docs", "--font-path", "docs/fonts", "--ignore-system-fonts"]; +typst(["compile", "--creation-timestamp", "1789344000", ...common, "docs/Main.typ", "CATS User Manual.pdf"]); +typst(["compile", "--features", "html", ...common, "docs/Web.typ", "docs/generated/manual.html"], expectedHtmlWarning); diff --git a/docs/check-manual.mjs b/docs/check-manual.mjs new file mode 100644 index 00000000..9940acba --- /dev/null +++ b/docs/check-manual.mjs @@ -0,0 +1,95 @@ +import { existsSync, readFileSync, readdirSync } from "node:fs"; +import { resolve } from "node:path"; + +const htmlPath = "docs/generated/manual.html"; +const html = readFileSync(htmlPath, "utf8"); +const webSource = readFileSync("docs/Web.typ", "utf8"); +const chapterFiles = readdirSync("docs/Chapters") + .filter((name) => name.endsWith(".typ")) + .map((name) => readFileSync(`docs/Chapters/${name}`, "utf8")) + .join("\n"); + +function requireCondition(condition, message) { + if (!condition) throw new Error(message); +} + +requireCondition(html.includes(''), "Missing manual canonical URL"); +requireCondition(html.includes("Last updated: 18 September 2026"), "Missing last-updated date"); +requireCondition(!html.includes("Version 2.1.2"), "Obsolete manual version remains"); +requireCondition(!html.includes("Revision History"), "Obsolete revision history remains"); +requireCondition(html.includes('
'), "Missing semantic manual article"); +requireCondition(html.includes("Configurator releases page'), + "Configurator releases link is not attached to its main text", +); +requireCondition( + !html.includes('>https://github.com/catsystems/cats-configurator/releases<'), + "Configurator releases URL leaked into web body text", +); +requireCondition(html.includes('href="#sec-FirmwareUpdates">6'), "Firmware Updates cross-reference number is stale"); +requireCondition(html.includes('href="#sec-Testing">8'), "Testing cross-reference number is stale"); +requireCondition(html.includes('href="#sec-AdvancedInfo">9'), "Advanced Information cross-reference number is stale"); +for (const heading of ["Hopping Pattern", "Synchronization", "Calibration of Sensors", "Kalman Filter", "Gain Scheduling"]) { + requireCondition(html.includes(`

${heading}

`), `Missing semantic technical heading: ${heading}`); +} + +const ids = new Set([...html.matchAll(/\sid="([^"]+)"/g)].map((match) => match[1])); +const anchors = [...html.matchAll(/href="#([^"]+)"/g)].map((match) => match[1]); +const missingAnchors = [...new Set(anchors.filter((anchor) => !ids.has(anchor)))]; +requireCondition(missingAnchors.length === 0, `Broken internal links: ${missingAnchors.join(", ")}`); +const sourceHeadingCount = (chapterFiles.match(/^=+\s+/gm) ?? []).length + (chapterFiles.match(/#heading\(level:/g) ?? []).length; +const articleHtml = html.slice(html.indexOf('
'), html.indexOf("
")); +requireCondition(!/href="#gls-/i.test(articleHtml), "Glossary terms must render as plain text"); +const generatedHeadingCount = (articleHtml.match(/ match[1]); +for (const link of new Set(sourceLinks)) { + requireCondition(html.includes(`href="${link.replaceAll("&", "&")}"`), `Missing external link: ${link}`); +} + +const imagePrefix = "https://raw.githubusercontent.com/catsystems/cats-embedded/docs/web-manual/docs/images/"; +const generatedImages = [...html.matchAll(/]*src="([^"]+)"[^>]*>/g)].map((match) => { + requireCondition(match[0].includes('loading="lazy"'), `Image is not lazy-loaded: ${match[1]}`); + requireCondition(match[0].includes('decoding="async"'), `Image does not decode asynchronously: ${match[1]}`); + requireCondition(match[1].startsWith(imagePrefix), `Unexpected image source: ${match[1]}`); + return decodeURIComponent(match[1].slice(imagePrefix.length)); +}); +const sourceImages = [...chapterFiles.matchAll(/doc-image\("([^"]+)"/g)].map((match) => match[1]); +requireCondition(new Set(generatedImages).size === new Set(sourceImages).size, "Generated image set does not match the chapter sources"); +for (const image of new Set(generatedImages)) { + requireCondition(existsSync(resolve("docs/images", image)), `Missing source image: ${image}`); + requireCondition(sourceImages.includes(image), `Unexpected generated image: ${image}`); +} + +const figureCount = (html.match(/CATS User Manual

CATS User Manual

Last updated: 18 September 2026

Glossary

Apogee
The highest point of the rocket during a parabolic flight
Barometer
A sensor that measures ambient barometric pressure
Calibrating
A flight state in which the flight computer is in safe mode and performs no actions
CLI
Command Line Interface, used to read and change flight-computer values without the Configurator
CRC
Cyclic Redundancy Check, used to verify that received data is not corrupted
Drogue Chute
A relatively small parachute deployed at apogee to stabilize and slow the rocket during descent
FHSS
Frequency Hopping Spread Spectrum, a protocol that transmits telemetry data across multiple carrier frequencies
FreeRTOS
An operating system for embedded CPUs and the backbone of the CATS software
FSM
Finite State Machine, a model that describes the flight phases, how transitions between them occur, and which transitions are permitted
GNSS
Global Navigation Satellite System, such as GPS or Galileo
I/O
Input/Output, a collective term for the system’s inputs and outputs
IMU
Inertial Measurement Unit, a sensor that measures linear acceleration and angular velocity
Kalman Filter
A filtering technique used to estimate states according to physical laws and measurements
Liftoff
The event that marks the start of powered ascent
Main Chute
The larger parachute deployed at a specified height above ground level to slow the rocket before landing
Patch Antenna
A flat, highly directional antenna used by the CATS Vega to receive GNSS signals
Power Supply
A source of electrical power, typically a battery in a rocket
PWM
Pulse Width Modulation, a method used to control most modern servos
Pyro
A pyrotechnic charge initiated by applying current through two electrical leads
Ready
A flight state; when in this state, liftoff can be detected
RF
Radio Frequency
Servo
A small electric actuator whose position is controlled by a PWM signal
Touchdown
The final flight phase, entered when the rocket lands
UART
A serial communication interface used to exchange data between devices

Disclaimer

The use of the CATS System is at your own risk. The CATS System must always be used in conjunction with a second safety system that operates in a different manner, such as motor ejection or another electronic system, to ensure maximum safety.

The manufacturer is not liable for any damages that may occur as a result of using the CATS System, and will not be held responsible for any damages inflicted on third parties.

Do not touch the CATS Vega while it is powered through the battery port because high currents flow through the board.

The manufacturer cannot be held liable for any program errors or malfunctions in the software.

The hardware warranty covers manufacturing errors and defects in workmanship and materials for a period of two years from the date of purchase. This warranty does not cover damage caused by improper handling, accidents, or other external factors. In the event of a covered manufacturing error or defect, the manufacturer will repair or replace the hardware at no cost to the user. To make a claim under this warranty, the user must provide proof of purchase and report the issue to the manufacturer within the warranty period. The manufacturer reserves the right to inspect the hardware and determine the cause of any reported issue before providing a repair or replacement. This warranty is non-transferable and only applies to the original purchaser of the hardware.

Important Regulatory Information

FCC Part 15 Compliance

This equipment has been designed to operate in accordance with Part 15 of the FCC Rules for unlicensed radio frequency devices. To maintain cooperative use of the shared spectrum, operation should be subject to two general conditions: (1) the device should not cause harmful interference, and (2) it must accept any interference received, including interference that may cause undesired operation.

Intended Use and Operational Constraints

The CATS Vega and Ground Station are developed primarily for educational, professional, and experimental use within amateur High Power Rocketry. In the United States, rockets of this class are considered aircraft by the Federal Aviation Administration (CFR 14 §101.25). Operators should adhere to FAA and National Fire Protection Association (NFPA) safety codes, which typically require maintaining a safe distance of at least 1,500 feet from populated buildings or uninvolved persons. Due to the high-power radio frequency emissions in the 2.4 GHz band, users are strongly advised against operating this telemetry system in residential areas to prevent potential disruptions to local consumer networks.

Hardware Certification and Radio Frequency (RF) Operations

The system utilizes Semtech SX1280 RF modules operating in the 2.4 GHz Industrial, Scientific, and Medical (ISM) band. As this operates on a shared, unlicensed band, users are not protected against interference from other ambient RF sources. We have made good faith efforts to ensure the hardware design follows standard EMC practices; however, should your system cause interference with licensed radio systems or residential Wi-Fi networks, you are expected to power down the device until the interference issue is resolved.

European Union (EU) and CE Compliance Notice

For operation within the European Union (EU) and the European Economic Area (EEA), this equipment is subject to the Radio Equipment Directive (RED) 2014/53/EU. Users operating within the EU must configure the telemetry output via the CATS Configurator to comply with the ETSI EN 300 328 harmonized standard, which strictly limits 2.4 GHz wideband transmissions to a maximum of 100 mW (20 dBm) Equivalent Isotropic Radiated Power (EIRP).

Exception for Licensed Amateur Radio Operators: Users holding a valid amateur radio license are authorized to operate at higher power levels within the 2.4 GHz amateur allocation. Such operation must strictly adhere to national amateur radio regulations, including station identification rules and prohibitions on encrypted commercial data.

Environmental and Safety Declarations

This product is factory-assembled utilizing lead-free manufacturing processes with the intent of aligning with global Restriction on Hazardous Substances (RoHS) principles. Please practice responsible disposal at the end of the product’s life cycle by recycling it as electronic waste rather than disposing of it in standard household trash.

Introduction

Welcome to the CATS User Manual. The following pages explain the CATS System so that you can install, configure, test, fly, and recover a rocket using the CATS Vega flight computer and CATS Ground Station. Each component has a practical operating section, while later chapters provide additional technical detail.
If you have feedback, suggestions, or need further help, contact us on our Discord server. The CATS ecosystem is open source; source code and hardware designs are available on our GitHub page.

Coverage of This Manual

This manual covers the use of the CATS Vega flight computer and its Ground Station. It explains how the flight computer works, how to connect it to a Power Supply and deployment actuators, and how to configure it for your flight trajectory.
This manual does not cover everything that can be done with the CATS System. In particular, it does not explain how to modify the software or hardware, or how the software works in detail. For further information about those topics, contact us on our Discord server.

Module Overview

The CATS System has three main components.
CATS Vega: The flight computer installed inside your rocket.
Ground Station: The receiver that displays and records telemetry, supports recovery, and controls bench testing.
Configurator: The desktop application used to configure and update the CATS Vega, review a configuration before flight, manage profiles, and analyze completed flights.

Basic Functionality

This section provides a broad overview of the CATS System for users who are new to rocketry. The following sections explain each topic in greater detail.
The CATS Vega is the core of the system. Its main purpose is to deploy the drogue chute at Apogee and the main chute at a user-configurable height above ground level. To do this, it combines barometric and accelerometer data to estimate height above ground level and velocity.
The CATS System defines five events: Liftoff, Burnout, Apogee, Main Deployment, and Touchdown. The onboard control system triggers these events automatically, while the user defines the actions performed when each event occurs.
Up to eight actions can be assigned to each event. Actions include delays, pyro-channel and servo-channel triggers, and low-level I/O signals. This allows the user to define how the deployment mechanism is actuated. Most commercial recovery mechanisms use pyro or servo channels, and the CATS Vega provides two of each.
At the same time, the system transmits important data to the Ground Station, including GNSS data, current height, velocity, and flight state. The data is also recorded in onboard flash memory.
The Ground Station is also used for testing mode, in which the user can trigger configured events to test separation mechanisms.

CATS Vega

This section describes how the flight computer works and how to configure it for a flight. The How to Use section explains its basic features. For more detailed information, refer to Section 9.

Figure 1: CATS Vega

Hardware

Specifications

Size100 × 33 × 15 mm (without the antenna)
Weight33 g
Input Voltage7 - 24 V
Power Consumption100 mA
Number of Pyro channels2
Number of Servo channels2
Number of IOs1
Additional IOUART
Servo Power5 V / 3 A max.
MicrocontrollerSTM32F4
Flash Memory16MB
IMULSM6DSO32
BarometerMS5607
Radio FrequencyISM 2.4GHz
Radio PowerUp to 1W
Radio RangeTested to 10km @100mW
Table 1: Vega Specifications

Hardware Overview

This section provides a quick hardware overview and shows the location of each port. The numbered markers in Figure 2 correspond to the following list.

  1. Switch Port; Connect a manual switch between the two terminals.

  2. Battery Port; Connect a battery to these terminals and observe the correct polarity.

  3. Buzzer; Indicates flight-computer readiness and status through beeping patterns, as explained in Section 4.4.

  4. Status LEDs; The POWER LED is illuminated when power is present. The STATUS LED blinks when the system is operating normally.

  5. USB Connector; The connector is on the other side of the board.

  6. Test Button; If this button is held during startup, the board enters testing mode if a testing phrase has been configured.

  7. Servo Connector; This connector fits the standard servo connectors. Two servos can be connected to this connector.

  8. Telemetry LEDs; The GNSS LED blinks whenever GNSS coordinates are received. The LINK LED blinks after a connection to the Ground Station has been established.

  9. Low-Level I/O and UART Connector; Connect external hardware to this port to exchange data with the CATS board.

  10. Pyro LEDs; These red LEDs are turned on when continuity of the Pyro channel is detected.

  11. Pyro Channel 1; Connect a pyrotechnic charge or another supported device to this connector.

  12. Pyro Channel 2; Connect a pyrotechnic charge or another supported device to this connector.

  13. Antenna Connector; Connect an antenna here so that the CATS Vega can transmit data to the Ground Station.

Figure 2: CATS Vega board hardware specifications

Working Principle

This section briefly introduces the operating principles needed to understand the Vega flight computer’s configuration options.

Configurable Actions & Finite State Machine

The finite state machine (FSM), shown in Figure 3, controls the outputs of the Vega flight computer. When the flight computer is turned on, it starts in the Calibrating state. Every flight follows the sequence of states shown in Figure 3. Whenever a state transition occurs, the associated event is triggered.

Figure 3: Finite State Machine controlling the CATS software.

Each event can trigger one or more actions, such as a Pyro channel, Servo channel, or timer. Use the Configurator to assign actions to events, as described in Section 4.3.2.

Calibrating → TestingA telemetry command starts testing mode. This transition is available only if testing mode was enabled through the Configurator.
Calibrating → ReadyIMU (gyroscope and linear acceleration) readings are constant for 10 seconds.
Ready → ThrustingThe measured acceleration in any direction exceeds the user-defined acceleration threshold for 0.1 seconds.
Thrusting → CoastingThe measured acceleration in the “up” direction is smaller than 0 𝑚𝑠2 for 0.1 seconds
Coasting → DrogueThe estimated velocity needs to be smaller than 0 𝑚𝑠 for 0.3 seconds
Drogue → MainThe estimated height is below the user-defined height for 0.3 seconds
Main → TouchdownThe estimated velocity is in the bound [−3,3]𝑚𝑠 for 1 second
Table 2: FSM Transition Specifications

With this setup for state changes, the flight has a strictly controlled order. The Main event can only be thrown after the Apogee event. Events are also unique; during a flight only one event can be thrown.

Actions

When an event is triggered, the flight computer performs the actions assigned to it. Up to eight actions can be assigned to each event, supporting a wide range of applications. Examples include:

  • Enabling a camera at Liftoff using a Pyro channel,

  • Actuating a solenoid valve for two seconds using a Pyro channel,

  • Enabling some mechanism at engine burnout,

  • Disabling the camera at touchdown using the Pyro channel,

  • …

The full range of actions can be found below.

ActionParameter
Pyro 1ON/OFF
Pyro 2ON/OFF
Servo 1[0-1000]‰
Servo 2[0-1000]‰
Low-Level I/OON/OFF
Delay[0-15000] ms
RecorderON/OFF/PREFILLING
Table 3: Exhaustive List of all possible Actions

How actions can be configured is shown in section 7.

How to Use

Now that the hardware and software have been introduced, this section explains how to configure and mount the flight computer, update its software, and generate plots from flight data.

Connection to Your Computer

Before connecting your CATS Vega to your computer, download the Configurator from our releases page. Drivers are usually not required. If your computer does not recognize the device, refer to the troubleshooting steps in our wiki.

Description of the Configurator

The Configurator is the desktop application used to configure the CATS Vega, inspect its status, manage configuration profiles, run a preflight review, update firmware, and analyze flight logs. Download the latest release from the Configurator releases page.

When exactly one compatible Vega is connected, the Configurator selects it and connects automatically. If no automatic connection is made, use the device selector in the upper-right corner, choose the intended Vega, and select Connect. Use the refresh button if a newly connected device is not listed. When several Vegas are connected, always verify the selected device before changing or saving a configuration.

The left navigation provides the following work areas:

ConfigurationFlight settings, telemetry, testing, recorder settings, live board status, and hardware information.
Events & TimersActions assigned to flight events and the four configurable timers.
ProfilesExport the connected board configuration, compare another profile, and apply compatible settings.
PreflightA read-only review of the configuration, warnings, event sequence, timers, and outputs.
CLIDirect access to advanced flight-computer commands.
Flight LogsOpen local or onboard .cfl logs, generate plots, export data, or open a log in CATS Flights.
Firmware UpdatesDetect supported devices, retrieve official releases, and install or prepare firmware.
FlightsOpen CATS Flights in the default browser.
Table 4: Configurator navigation
Configuration

The Configuration page groups flight settings into General, Telemetry, Testing, Recording, Info, and Hardware Info panels. The General panel contains the main-deployment altitude, liftoff threshold, and initial servo positions. For most flights, use a liftoff threshold of 40 𝑚𝑠2 unless testing with the complete rocket shows that another value is required. The Telemetry and Testing panels contain the enable controls and phrases used by the Ground Station.

Changes shown in the Configurator are not persistent until Save is selected. Use Refresh to discard unsaved edits and reload the values stored on the Vega. Reset Config restores the default configuration after confirmation.

Events & Timers

The Events & Timers page shows all flight events and their assigned actions, followed by the four timers. Select Add Action to add an output, recorder command, or delay to an event. Existing actions can be edited or removed. Up to eight actions can be assigned to each event. Select Save after changing events or timers.

Each timer has a start event, a duration, and an event to trigger when the duration expires. A timer can provide a backup event or trigger Custom 1 or Custom 2 for a payload sequence. Triggering an event through a timer does not force the flight-state estimator into the corresponding state.

Configurator Configuration page connected to a CATS Vega
(a) Review and edit the connected Vega configuration.
Configurator Events and Timers page
(b) Review event actions and timer configuration.
Figure 4: Configurator Configuration and Events & Timers pages
Profiles

The Profiles page can export the complete connected-board configuration as a JSON profile. Opening another profile shows a setting-by-setting comparison with the connected Vega, including differences in configuration, events, timers, and recorder settings. Review compatibility warnings before applying a profile. You can apply the full compatible profile or individual differing settings, then save the resulting configuration to the board.

Preflight

The Preflight page reads the saved board configuration and produces a report without changing it. Run Preflight after saving the final configuration. Review every error and warning, especially testing mode, telemetry and recording status, deployment actions, liftoff threshold, timer cycles, and event ordering. The event timeline summarizes which actions run at each flight event and which active timers may trigger additional events.

Preflight is an additional configuration review, not a substitute for continuity checks, deployment-system testing, range procedures, or a redundant recovery system.

Configurator Profiles page showing connected-board settings
(a) Inspect the connected-board profile or compare another profile before applying it.
Configurator Preflight page showing a successful read-only review
(b) Run the read-only Preflight review after saving the final configuration.
Figure 5: Configurator Profiles and Preflight pages
CLI

The CLI page sends commands directly to the connected Vega. It is intended for advanced inspection and troubleshooting; normal configuration should be performed through the other pages. Common commands are listed in Section 9.5.

Flight Logs

The Flight Logs page accepts one Vega .cfl file selected through the file picker or dropped anywhere in the Configurator window. When a Vega USB drive is mounted, the page also lists its onboard logs. An onboard log can be viewed locally, saved as a copy, deleted from the Vega, or opened in CATS Flights.

After opening a log, use Export CSV for tabular data or Export HTML for interactive plots. Open in Flights hands the selected log to CATS Flights through the local browser; the log remains on the computer unless it is explicitly saved or shared there.

Configurator Flight Logs page listing an onboard Vega log
Figure 6: Configurator Flight Logs page with a connected Vega

Mounting

The CATS Vega does not require a specific mounting orientation. The system automatically detects the gravity vector for internal state estimation, so you can mount the board in any orientation.
The board has a length of 100 mm, a width of 33 mm and a total height of 15 mm. Three mounting holes secure the system to the rocket. The mounting holes are spaced 60 mm by 27 mm and are designed for M3 screws. Use spacers to prevent the electronics from touching the rocket. Download the system’s 3D files from our GitHub repository.
For reliable radio reception during flight, pay close attention to the area surrounding each antenna. Install the CATS flight computer in a radio-transparent section of the rocket, such as fiberglass or cardboard. Do not install it in a carbon-fiber section, which blocks RF signals. Ensure that the onboard Patch Antenna has a clear view of the sky for optimal GNSS reception, and keep the telemetry antenna away from metal objects.

After power-up, the system detects the up direction once it is stable. A beeping pattern and the Ground Station indicate when the flight computer enters the Ready state. In this state, the flight computer is armed and waiting for Liftoff. Do not move the rocket, and follow all safety guidelines. At this stage, the flight computer can be disarmed only by switching it off. For more information about calibration, refer to Sections 9.3 and 4.2.1.

Figure 7: CATS Vega board with the mounting hole and dimensions.

Battery, Switch and Actuators

The CATS Vega has one battery port, one switch port, two Pyro channels, two Servo channels, and one low-level I/O. The following sections briefly explain each port. Table 5 summarizes the most important parameters. For more information about the board hardware, refer to Section 4.1 and the labeled board diagram in Figure 2.

Battery Port
The battery port supports 7 to 24 volts. Use a 2- to 5-cell LiPo or Li-ion battery and ensure that its actual voltage remains within this range. The battery port is protected against reverse polarity.

Switch Port
The switch port allows the user to add a mechanical switch to the system. If this switch is turned off, the system is fully disconnected from power.

Pyro Channels
The Pyro channels apply the battery voltage to the connected circuitry with a voltage drop of approximately 1 V. An electric match is normally connected to a channel to ignite a black-powder charge. The channels can also power other devices. For example, they can actuate solenoid valves (with an external flyback diode), power cameras, or power other electronic circuits. By default, the maximum continuous current is approximately 1 A. The channels are short-circuit protected by a resettable PTC fuse. This current is more than sufficient to ignite electric matches before the fuse reduces it. If the connected load requires more current, the fuse can be bypassed with a solder jumper on the back of the board. In this configuration, stay below 5 A continuous or 20 A burst. Exercise extreme caution: a short circuit on the channel can damage the board.

Servo Channels
The Servo channels can actuate PWM Servos. An onboard voltage regulator reduces the battery voltage to 5 V to power the servos. The microcontroller’s power rail is completely separate from the 5 V Power Supply therefore, a short circuit on the servo power rail does not affect the system. A maximum current of 3 A can be drawn. A PWM signal is always applied to each Servo channel, and the endpoints can be changed in the Configurator.

Low-Level I/O
The low-level I/O can send a signal to another system. The voltage level is 3.3 V, and the pin is connected directly to the microcontroller. Therefore, the I/O should be used only for signal transmission, not to actuate a recovery mechanism.

I/O Specification

I/ODescriptionLimits
Battery PortConnect battery7-24 V
Switch PortConnect mechanical switchn.a.
Pyro ChannelsConnect up to two pyrotechnic charges or other devicesBattery voltage / 5 A
Servo ChannelsUsed for Servo actuation, up to two Servos5 V / 3 A
Low-Level I/OUse only for signal transmission, not actuation3.3 V / 10 mA
Table 5: Overview of the I/Os

Setting up the Minimal Flight Configuration

For nominal flight performance, several parameters must be configured before every flight. In particular, the user must know:

  • Expected maximum acceleration

  • Recovery mechanism for the Drogue Chute

  • Recovery mechanism for the Main Chute

  • Time until Apogee (optional)

  • Desired deployment altitude of the Main Chute

  • Time until Main Chute deployment (optional)

With this information, the user can configure the flight computer. Timers are optional and should be used only as a backup.

  1. Connect the flight computer to your computer.

  2. Open the Configurator and connect to the board as described in Section 4.3.2.

  3. On the General page, set the Liftoff threshold. We recommend using a Liftoff acceleration threshold of 40𝑚𝑠2, but make sure that it is around 20𝑚𝑠2 lower than your maximum expected acceleration.

  4. On the General page, set the main altitude to your desired height. This is the height above ground level where the Main Chute will be deployed.

  5. If you use a Servo channel in either of your recovery mechanisms, it is now also the time to set the initial Servo position.

  6. On the Configurator’s General page, set the link phrase for your CATS Vega.

  7. Make sure that the Testing Mode is disabled.

  8. Save the settings.

  9. Open the Events & Timers page.

  10. For the apogee event, set your deployment mechanism as described in 4.3.2.

  11. For the main deployment event, set your deployment mechanism as described in 4.3.2.

  12. Save the settings.

  13. (Optional) On the same page, open the timers section.

  14. (Optional) Set the Timer One start event to Liftoff and the Timer One end event to apogee. Set the time until apogee with 1-2 seconds margin.

  15. (Optional) Set the Timer Two start event to Liftoff and the Timer Two end event to main deployment. Set the time until main deployment with 10-60 seconds margin, depending on the flight time.

  16. Save the settings.

  17. Set the same link phrase on your Ground Station. Navigate to Settings, select Link Phrase, and enter the same phrase.

The flight computer is now ready to be installed in the rocket. For this flight configuration, complete the following steps:

  1. Mount the flight computer to your rocket.

  2. Connect the switch to the switch port.

  3. Connect the battery to the battery port.

  4. Connect the recovery mechanism for the apogee event.

  5. Connect the recovery mechanism for the main event.

  6. Place the rocket on the launch pad.

  7. Turn on the flight computer with the switch.

  8. The Ground Station will begin receiving data.

  9. Wait for the flight computer to finish calibrating and show READY on the Ground Station.

  10. The flight computer is now armed. Every 6 seconds, the flight computer beeps twice to indicate that it is in the Ready state.

  11. Launch your rocket!

How to Get the Data on Your Computer

After the flight, connect the board to a computer with a USB-C cable. The flight computer appears as a USB drive containing .cfl flight logs and their associated files. Copy the required files before disconnecting the board, or use the Configurator’s Flight Logs page to browse, view, save, or delete onboard logs.

Figure 8: USB drive when the CATS Vega is plugged into the user computer.

Visualizing the Flight Data

Open the Configurator’s Flight Logs page and choose or drop a .cfl flight log. The Configurator plots altitude, velocity, acceleration, angular velocity, linear acceleration, pressure, state changes, and actions. Export the data as .csv files for further processing or as an .html file with interactive plots. You can also open the log in CATS Flights. A legacy Python plotting tool is described in Section 9.4 for users who need a customizable local workflow.

Software Updates

Use the Configurator’s Firmware Updates page for normal Vega updates. The complete procedure, including Ground Station and radio-receiver updates, is described in Section 6.

Beeping Patterns

The CATS Vega flight computer uses beeping patterns to indicate its current state or a potential error. The tables below list the available patterns.

StateDescriptionPattern
BootupThe flight computer has booted up.Bootup beeping pattern
Calibrating → ReadyThe flight computer has switched from the Calibrating state to the Ready state.Calibrating to ready beeping pattern
ReadyCalibration was successful, and the flight computer is in the Ready state.Ready beeping pattern
TestingThe flight computer is in testing mode. This pattern sounds only after the computer is rebooted.Testing beeping pattern
Testing ArmedThe flight computer is in the armed testing state.Testing armed beeping pattern
Table 6: Overview of state beeping patterns.

Ground Station

The Ground Station is the counterpart to the CATS Vega. It receives data from the flight computer and sends commands to it. It displays the rocket’s position, velocity, system health, and other important information in real time. This chapter explains how to use the Ground Station and describes its operating principle.

Figure 9: Ground Station

Hardware

Overview

The Ground Station is built around an ESP32-S2 microcontroller and features a transflective display that remains readable in bright sunlight. It has 4 MB of internal flash, including a 1 MB FAT data partition for logs and firmware-transfer files.

Specifications

MicrocontrollerESP32-S2
Flash Memory4 MB internal; 1 MB data partition
BatteryLi-Ion 18650
Power Consumption60mA
Charging Current500mA
ScreenLS027B7DH01
Radio2x SX1280
Radio RangeTested to 10km @100mW
GNSSATGM336H-5N
Table 7: Ground Station Specifications

How to Use

This section covers the basic use of the Ground Station. For more advanced information, refer to the later sections.

Explanation of All Menus

Use the joystick to move left, right, up, and down. Press A to open a menu, select an item, or confirm an action. Press B to go back. Arrows and hints at the edges of the display indicate when another page or action is available.

Ground Station main menu rendered by the simulator
Figure 10: Ground Station main menu
Live

The Live screen shows telemetry from the connected Vega or Vegas. It displays flight state, altitude, vertical velocity, battery voltage, pyro continuity, errors, and radio-link information. Press Left for the GNSS view and Right for the downrange view. The downrange view uses the Ground Station’s own GNSS position to show the rocket’s relative direction and distance.

The link indicators include:

  • AGE - Time since the last received packet. A link is treated as disconnected after five seconds without a packet.

  • SNR - Signal-to-noise ratio in dB. Lower values indicate a noisier radio environment.

  • LQ - Percentage of expected packets received during the recent measurement window.

  • RSSI - Received signal strength in dBm. More negative values indicate a weaker received signal.

Ground Station live telemetry screen
(a) GNSS telemetry from both receivers in Single mode.
Ground Station live downrange screen
(b) Relative downrange distance and direction.
Figure 11: Ground Station Live views
Recovery

The Recovery screen guides you toward the last valid GNSS position received from the rocket. It shows the selected rocket, distance, relative direction, and whether a usable location is available. Calibrate the Ground Station compass outdoors near the launch site and away from large metal objects before relying on direction guidance.

In Dual receiver mode, press Up or Down to choose Link 1 or Link 2. Press Right to show a QR code for the selected last location; scan it with a phone to open the coordinates in a mapping application. If the other link also has a valid location, press Right again to switch QR-code pages. Press Left to return to direction guidance.

Ground Station recovery direction screen
(a) Direction and distance to the last received location.
Ground Station recovery location QR code
(b) QR code for transferring the selected last location.
Figure 12: Ground Station Recovery views
Testing

The Testing screen arms testing mode and manually triggers configured flight events. Triggered events execute their assigned actions. Read Section 8 completely before using this screen.

Data

The Data screen lists logs stored on the Ground Station. An active recording is marked as active. Select a log to view its duration, maximum altitude and velocity, flight state, and recorded locations. When a valid location is available, open its QR-code page to transfer the coordinates to a phone.

The options page can finalize the active log or delete a completed log after confirmation. Disconnect the Ground Station USB drive before deleting a log. Finalizing stops the active recording and closes its files; deleting permanently removes the selected completed log.

Ground Station list of recorded flight logs
(a) Select a stored Ground Station flight log.
Ground Station flight-log statistics
(b) Review recorded statistics and last locations.
Figure 13: Ground Station Data views
Sensors

The Sensors screen shows raw IMU, magnetometer, and GNSS readings. Press Right or Down to open the Compass / 3D Orientation page, which shows the Ground Station’s heading, pitch, and roll. Press Left or Up to return to raw readings.

Press A to start compass calibration and follow the on-screen instructions. Rotate the Ground Station slowly through multiple orientations, away from large metal objects and magnets. When calibration reaches 100%, confirm the result to save it.

Ground Station raw IMU and GNSS sensor readings
(a) Raw IMU, magnetometer, and GNSS readings.
Ground Station compass and 3D orientation screen
(b) Compass heading, pitch, and roll.
Figure 14: Ground Station Sensors views
Settings

Settings are divided into three pages. Move Left or Right while no setting is selected to change pages.

PageSettingPurpose
TelemetryReceiver ModeSingle uses both receivers for one Vega; Dual assigns one Vega to each receiver.
TelemetryLink Phrase 1Phrase used by both receivers in Single mode or the left receiver in Dual mode.
TelemetryLink Phrase 2Phrase used by the right receiver in Dual mode.
TelemetryTest PhrasePhrase required to arm Vega testing mode.
PreferencesStop LoggingStop at landing or continue until manually finalized.
PreferencesTime ZoneLocal offset from UTC.
PreferencesUnitsMetric or imperial display units; recorded data remains metric.
PreferencesStartup AnimationAnimated startup or static CATS logo.
SystemFirmware VersionsGround Station and both receiver-firmware versions.
SystemUSB DriveView or disconnect the shared USB storage.
SystemSelf-TestFactory-oriented automatic and guided hardware checks.
SystemUpdate FirmwareUpdate the Ground Station application or both radio receivers.
Table 8: Ground Station settings
Ground Station Telemetry settings page
(a) Telemetry settings.
Ground Station Preferences settings page
(b) Display and recording preferences.
Figure 15: Ground Station Telemetry and Preferences settings
Ground Station System settings page
Figure 16: Ground Station System settings

Telemetry Modes

The Ground Station’s telemetry settings include a mode option. Because the Ground Station has two receivers, it supports two modes.

In Dual mode, the Ground Station can track two Vega flight computers. This is useful when a section separates from the rocket and you want to track it as well as the main body.

In Single mode, the Ground Station tracks one Vega flight computer. Packets from both receivers are combined, allowing more data to be received than with a single receiver. For best diversity performance, use one directional antenna and one omnidirectional antenna.

Data Streaming via USB

When connected to a computer via USB, the Ground Station continuously streams each newly received telemetry packet through its virtual serial port. Each line identifies the radio link and includes the timestamp, flight state, GPS coordinates, altitude, velocity, and battery voltage; in dual-receiver mode, data from both links is reported.

The serial stream emits one line per newly received telemetry packet. All units are fixed and are not affected by the Ground Station’s unit settings:

  • Link: Receiving radio link number (1 or 2)

  • Ts: Flight-computer uptime in seconds, with 0.1 s resolution

  • State: Numeric flight state (0–7: Invalid, Calibrating, Ready, Thrusting, Coasting, Drogue, Main, Touchdown)

  • Lat / Lon: GPS coordinates in decimal degrees

  • Alt: Estimated altitude in meters

  • Vel: Estimated vertical velocity in meters per second

  • V: Flight-computer battery voltage in volts, with 0.1 V resolution

Figure 17: Ground Station telemetry data from both radio links streamed over the USB serial port.

Charging

The Ground Station is powered by a Li-ion 18650 battery. A fully charged battery provides more than 8 hours of operation. Charge the battery through the USB port. At a charging current of 500 mA, a full charge can take up to 6 hours. The LED next to the USB port lights while the battery is charging and turns off when charging is complete. To replace the internal battery, remove the battery cover on the back of the Ground Station. If the replacement battery has different specifications, the estimated remaining charge shown on the screen may differ from the actual percentage.

How to Get the Data on Your Computer

When connected by USB and not actively recording, the Ground Station shares its data partition as the CATS GS USB drive. Open the drive and copy the required .csv logs to the computer. The firmware reclaims the filesystem automatically when recording starts and shares it again after the log is finalized. Close files before recording or updating firmware, and use Settings → System → USB Drive when the drive needs to be disconnected manually.

Software Updates

Use the Configurator’s Firmware Updates page for normal Ground Station and radio-receiver updates. See Section 6 for the complete preparation, installation, verification, and recovery procedures.

Firmware Updates

The Configurator installs official stable firmware for the CATS Vega and Ground Station. It also prepares the firmware file that the Ground Station uses to update both of its radio receivers. Use the Firmware Updates page instead of downloading files and selecting programming tools manually.

Normal firmware installation is supported on Windows. On Linux and macOS, the Configurator can check connected devices and releases, but the standard release keeps flashing disabled until those USB workflows have completed hardware acceptance.

Before Updating

  1. Install the latest Configurator from the Configurator releases page. The Firmware Updates page updates connected CATS devices; it does not update the Configurator application itself.

  2. Save or discard any unsaved configuration changes. Firmware installation is disabled while the Configurator contains unsaved changes.

  3. Connect only the device that you intend to update. Disconnect deployment charges and place the Vega safely on the bench. Stop Ground Station tracking and recording, and close any files opened from its USB drive.

  4. Keep the device powered and connected until the Configurator or Ground Station reports that verification has completed.

Updating the Configurator

Download the current installer from the Configurator releases page, close the running Configurator, and run the installer. After installation, open the Configurator and confirm the expected App version in the footer.

Configurator Firmware Updates page after checking connected devices and official releases
Figure 18: Configurator Firmware Updates page after a successful device and release check

Updating the CATS Vega

  1. Connect the Vega by USB, open Firmware Updates, and select Check devices & releases.

  2. In the Vega panel, verify the detected device, installed version, and available version. Select Update Vega.

  3. Confirm that deployment charges are disconnected. If the installed version is unknown or the same version is being reinstalled, acknowledge the additional confirmation shown by the Configurator.

  4. Select Start update. The Configurator downloads and validates the official image, moves the Vega into its native USB DFU bootloader, erases and writes the application, reads it back for verification, and starts the new firmware.

  5. Leave USB connected while the Vega reconnects. The update is complete only after the Configurator verifies the running firmware version.

The Configurator prevents cancellation after the device starts transitioning into its bootloader. If the application reports a failed verification or reconnect step, leave the Vega connected and use the offered retry action. STM32CubeProgrammer and an ST-Link debugger are service and recovery tools, not part of the normal update procedure.

Updating the Ground Station

  1. Connect the Ground Station through its normal USB port. Stop tracking and recording, and close all files on the CATS GS drive.

  2. Open Firmware Updates, select Check devices & releases, and verify the Ground Station detected from its version.json information.

  3. Select Update Ground Station, confirm the safety prompt, and start the update. Keep the Ground Station connected while the Configurator enters TinyUF2, copies the official .uf2 image, and waits for the application to return.

  4. The update is complete only when the Configurator reads a fresh version.json and reports the installed version.

If automatic bootloader entry is unavailable, use Settings → System → Update Firmware → Ground Station on the device. Then return to the Configurator, check devices again, and start or retry the update. Do not use a 1200-baud reset; on this hardware it enters the ESP32 ROM bootloader rather than the supported TinyUF2 update path.

Updating the Ground Station Radio Receivers

The Configurator validates and copies the radio image, while the Ground Station performs the installation on both receiver modules.

  1. Connect the normal CATS GS USB drive, open Firmware Updates, and select Check devices & releases.

  2. In the Ground Station radios panel, verify the detected drive and available version. Select Prepare radio firmware and confirm that tracking, recording, and file access have stopped.

  3. After preparation succeeds, close all files and safely eject the CATS GS drive from the computer.

  4. On the Ground Station, open Settings → System → Update Firmware → Radio Receivers.

  5. Select the prepared .bin file from the telemetry_firmware directory and confirm the update. Keep the Ground Station powered while it updates and verifies both radios.

  6. Do not leave the update screen until it reports Both radios verified and shows the expected version for Link 1 and Link 2.

  7. Power-cycle the Ground Station, reconnect its normal USB drive, and select Check devices & releases in the Configurator to refresh all reported versions.

The following Ground Station screens show the complete on-device sequence. Filenames, versions, sizes, and checksums are examples; use the file and version prepared by your Configurator.

(a) Open Update Firmware from the System settings page.
(b) Select Radio Receivers.
(c) Select the prepared radio image.
(d) Confirm the selected image and keep power connected.
(e) Wait while each receiver is written and verified.
(f) Confirm that both radios were verified.
Figure 19: Ground Station radio-receiver update sequence

Recovering an Interrupted Update

Keep the device connected and follow the retry action shown by the Configurator. A Vega that remains in native DFU can be written and verified again. A Ground Station already in TinyUF2 can be checked again before retrying the validated update. If a radio update was interrupted, reopen the Ground Station’s Radio Receivers update screen and run the prepared file again, then verify both reported versions.

If a device cannot enter its supported bootloader or cannot be detected after the documented retries, disconnect all outputs and contact CATS support. Direct programming through STM32CubeProgrammer or an ST-Link debugger is reserved for service recovery and factory provisioning.

Example Configurations

These examples show how hardware, flight events, actions, and timers fit together. Adapt all thresholds, deployment altitudes, delays, and output settings to the actual rocket and recovery system.

Simple Dual-Deployment Example

This example uses a pyrotechnic charge on Pyro Channel 1 for the drogue parachute and a second charge on Pyro Channel 2 for the main parachute.

AreaExample valuePurpose
ConfigurationLiftoff threshold: 40 𝑚𝑠2Detect liftoff after the configured acceleration is sustained.
Events & TimersApogee → Pyro 1 ONDeploy the drogue parachute at detected apogee.
Events & TimersMain Deployment → Pyro 2 ONDeploy the main parachute below the configured main altitude.
Events & TimersTimer: Liftoff → Apogee after 15 sProvide a time-based backup for the apogee event.
Table 9: Simple dual-deployment example

Connect the battery and switch, then connect the deployment circuits to Pyro Channels 1 and 2 as shown below. Keep the charges disconnected while checking continuity and event behavior.

Figure 20: CATS Vega with a battery, switch, Pyro 1 and Pyro 2 connected.

In Preflight, verify the main-deployment altitude, liftoff threshold, timer, event sequence, and both pyro actions. Use the procedure in Chapter 8 to test the configuration with safe substitutes before connecting energetic devices.

Advanced Recovery Example

This example adds timed actions, a servo-deployed main parachute, a camera, and a low-level output. It illustrates the available building blocks; it is not a recommended configuration for a specific vehicle.

AreaExample valuePurpose
ConfigurationLiftoff threshold: 40 𝑚𝑠2Detect liftoff.
ConfigurationMain altitude: 350 mTrigger the Main Deployment event below 350 m during descent.
ConfigurationServo 1 initial position: mechanism closedHold the main-deployment mechanism in its safe initial position. Determine the actual value on the bench.
Events & TimersApogee → Pyro 1 ON; delay 2 s; Pyro 1 OFFOperate a solenoid valve for two seconds.
Events & TimersMain Deployment → Servo 1 deployed positionOpen the main-deployment mechanism. Determine the deployed value on the bench.
Events & TimersLiftoff → Pyro 2 ON; Touchdown → Pyro 2 OFFControl an externally powered camera through a suitable interface.
Events & TimersBurnout → I/O ONAssert the low-level output at burnout.
Events & TimersTimer: Liftoff → Apogee after 45 sProvide a time-based backup for the apogee event.
Table 10: Advanced recovery example

Connect the battery and switch, the solenoid-valve interface to Pyro Channel 1, the camera interface to Pyro Channel 2, and the main-deployment mechanism to Servo Channel 1 as shown below. Observe the electrical limits in Section 4.1 and use external drivers where the load requires them.

Figure 21: CATS Vega with a battery, switch, solenoid valve, camera, and servo connected.

Before flight, use Preflight to inspect the complete timeline, including delayed actions and timer-triggered events. Test each event individually in testing mode, then disable testing mode, reboot the Vega, and run Preflight again.

Testing

Testing mode lets you trigger the Vega’s configured events from a Ground Station while the system is secured on the bench.

What Testing Mode Does

Testing mode stops normal flight-state processing. After the Vega and Ground Station enter armed testing mode, the Ground Station can trigger any configured event. Every action assigned to that event is executed, including pyrotechnic, servo, low-level I/O, recorder, and delayed actions.

Before You Start

  • Secure the Vega, battery, Ground Station, and every connected mechanism on a suitable test bench.

  • Disconnect pyrotechnic charges, motors, and other energetic devices unless testing them is the specific purpose of the procedure.

  • In the Configurator, review Events & Timers and confirm every action that will run for each event.

  • Open Preflight and resolve every reported configuration or connection problem.

  • Confirm that the Vega and Ground Station use the same receiver mode, link phrase, and testing phrase.

Enabling and Using Testing Mode

  1. Connect the Vega to the computer and open the Configurator. The Configurator connects automatically when exactly one compatible Vega is available; otherwise, select it manually.

  2. Open Configuration, enable Testing Mode, and set a testing phrase. Save the configuration.

  3. Reboot the Vega. Testing mode does not become active until after the reboot.

  4. Confirm that the Vega emits the Testing beeping pattern described in Section 4.4.

  5. Turn on the Ground Station. In Settings → Telemetry, select the matching receiver mode and set Link Phrase 1 and Test Phrase to the values configured on the Vega.

  6. Open Testing on the Ground Station. Read the safety notice, press the A button to continue, and wait for the Ground Station to arm the Vega.

  7. Confirm that the Vega emits the Armed Testing beeping pattern.

  8. Select an event, review the confirmation screen, and confirm only when the test area is clear. Observe every configured output and delayed action.

  9. Repeat only the checks required for the test. If the telemetry link is lost, return to the Testing menu and arm the system again.

Ground Station testing-mode safety notice
(a) Read the complete safety notice.
Ground Station testing-mode arm confirmation
(b) Continue only when the connected Vega is in testing mode.
Ground Station waiting for testing mode to start
(c) Wait while the Ground Station arms the Vega.
Ground Station testing event selection screen
(d) Select the configured event to test.
Figure 22: Entering testing mode and selecting an event
Ground Station confirmation before triggering a test event
Figure 23: Final confirmation before triggering the selected event

Returning to Flight Configuration

  1. Exit Testing on the Ground Station.

  2. Reconnect the Vega to the Configurator, disable Testing Mode, and save the configuration.

  3. Reboot the Vega and confirm that the Testing beep pattern is no longer emitted.

  4. Run Preflight again before installing energetic devices or preparing the rocket for flight.

Advanced Information

This section explains the core components of the CATS Vega board in greater detail. It is intended for advanced users.

Software Overview

This section provides a brief overview of the software architecture. It is intended for advanced users with some programming experience; understanding it is not required to use the flight computer.
The software is implemented in C++ and uses FreeRTOS as its foundation. The hardware is initialized first, after which the tasks are started. Figure 24 shows the running tasks.

Figure 24: Illustration of the different FreeRTOS tasks interacting with each other and the hardware. The black circle ‘Settings’ is just a memory region that is being accessed by different tasks.

The following list briefly describes each task.

  • Sensor Read reads the Barometer and IMU data and provides it to the Preprocessing task.

  • Preprocessing converts the raw barometric pressure to altitude above ground level and the linear acceleration to acceleration in the “up” direction. It provides the processed data to the FSM and State Estimation tasks.

  • State Estimation estimates the current height and velocity based on the Preprocessing task’s output and the FSM state.

  • FSM computes the current flight phase from the State Estimation and Preprocessing outputs.

  • Transceiver handles communication between the main chip and the telemetry chip.

  • USB Communicator is a group of three tasks that handle the interface between the flight computer and the user’s computer. These tasks do not start when USB is not connected.

  • Peripherals triggers all user-defined events.

  • Health Monitor checks values like the buzzer and the battery voltage.

  • Recorder uses a queue to record all data to the flash chip.

  • Buzzer actuates the buzzer.

Telemetry

The telemetry system uses 2.4 GHz LoRa and FHSS (Frequency-Hopping Spread Spectrum). FHSS makes transmissions more resistant to interference and more difficult to intercept. It also allows more devices to use the same frequency band with little or no effect on link quality.

Hopping Pattern

The link phrase defines the hopping pattern. It is hashed with a CRC−32 algorithm, and the resulting value seeds a pseudo-random number generator. The generator runs 20 times to define the hopping pattern. As a result, a given link phrase always produces the same pattern. The transmitter and receiver must use the same link phrase to communicate.

Figure 25: FHSS transmission example

Synchronization

The receiver waits on the first frequency until it receives a synchronization packet. This packet contains the link CRC, which identifies the transmission source. If the remote CRC matches the local value, the receiver hops to the next frequency and waits for data. Each data packet contains a checksum for validating its contents. The receiver measures the interval between packets and hops to the next frequency when a packet is not received within the estimated interval. It can perform 30 hops without receiving a packet before synchronization is lost. If the connection is lost, the receiver returns to the first frequency.

Estimation Algorithms

State estimation calculates the rocket’s velocity and altitude from barometric pressure and linear acceleration in the 𝑧 direction.

Calibration of Sensors

Linear acceleration is calibrated when the system enters the Ready state. This allows the flight computer to be mounted in any orientation. The gravity vector is used to calculate the up direction, which is then used throughout the flight.

During Calibrating and Ready, the current altitude above sea level is continuously estimated. Altitude above ground level, the value used during flight, is calculated from the altitude above sea level. This calculation assumes that barometric pressure changes very slowly. When Liftoff is detected, the altitude above sea level is fixed, and only the altitude above ground level is updated.

Kalman Filter

A Kalman Filter estimates altitude and velocity from the calibrated values. Its derivation is described below. We define the state and noise as

𝑥(𝑡)=(ℎ(𝑡)𝑣(𝑡)𝑎𝑜(𝑡))𝑣=(𝑣1𝑣2)

where ℎ is the altitude above ground level, 𝑣 is the vertical velocity, and 𝑎0 is the estimated offset of the measured vertical acceleration. 𝑣1 is the noise applied to the vertical acceleration, and 𝑣2 is the noise used to estimate the linear-acceleration offset.
The system input is 𝑢(𝑡), the linear acceleration measured in the 𝑧 direction.

𝑥̇(𝑡)=(𝑣(𝑡)𝑎(𝑡)𝑎0̇(𝑡))=𝐴⋅𝑥(𝑡)+𝐵⋅𝑢(𝑡)+𝐺⋅𝑣(𝑡)=(010001000)⋅(ℎ(𝑡)𝑣(𝑡)𝑎𝑜(𝑡))+(010)⋅𝑢(𝑡)+(001001)⋅(𝑣1(𝑡)𝑣2(𝑡))

This is discretized using a first-order approximation:

𝐴𝑑=𝑒𝐴𝑇𝑠𝐵𝑑=∫0𝑇𝑠𝑒𝐴𝑑𝑡𝛿𝑡⋅𝐵𝐺𝑑=∫0𝑇𝑠𝑒𝐴𝑑𝑡𝛿𝑡⋅𝐺

which gives the system

𝑥(𝑘+1)=𝐴𝑑⋅𝑥(𝑘)+𝐵𝑑⋅𝑢(𝑘)+𝐺𝑑⋅𝑣(𝑘)

The process measurement noise matrix becomes

𝑄(𝑘)=(𝑄acc(𝑘)00𝑄acc_0(𝑘))

The measurement step assumes that altitude has already been calculated from barometric pressure using the standard barometric formula.

𝑧(𝑘)=ℎmeas(𝑘)+𝜔(𝑘)=(𝑝(𝑘)𝑝015.257−1)⋅𝑇0+273.15𝐿−ℎ0+𝜔(𝑘)

where 𝐿=−0.0065, 𝑇0=15 C, 𝑝0=101250 Pa, ℎ0 is the calibrated altitude above sea level, and 𝜔 is the measurement noise.

The measurement function is

𝑧(𝑘)=𝐻⋅𝑥(𝑘)=(100)⋅(ℎ(𝑘)𝑣(𝑘)𝑎𝑜(𝑘))

The measurement-noise matrix becomes a scalar:

𝑅(𝑘)=𝑅height

The standard Kalman-filter equations can then propagate the state.

Gain Scheduling

Gain scheduling reduces reliance on the barometer during high-velocity flight, because barometric measurements can behave unpredictably in the transonic regime.

At Liftoff and while the rocket is moving quickly, the accelerometer is weighted more heavily when estimating altitude and velocity. At lower velocities, barometric pressure is weighted more heavily because accelerometer drift affects the estimate. As the rocket arcs over, the quality of the accelerometer measurement also decreases.

Two variables control the relative trust in the sensors: 𝑄acc and 𝑅height. In the algorithm, 𝑄acc remains constant, while 𝑅height changes during flight. The conditions for changing 𝑅height are shown below.

𝑅height={𝑅initialfor state = MOVING or IDLE𝑅maxfor state = LIFTOFF𝑅max⋅𝑓(𝑣)for state = COASTING𝑅initialotherwise

where 𝑓(𝑣) depends on the current velocity.
This gain scheduling effectively filters unexpected barometric measurements at high velocities.

Using the Python Plotting Tool

For more control over flight data, use the legacy Python plotting tool. It provides the Configurator’s plotting functionality in a form that is easier to customize.
To visualize logs recorded by the Vega flight computer, clone the cats-logs repository and run the log_visualizer.py script. Git and Python 3 must be installed to download and run the script.

To visualize your logs, follow these steps:

git clone https://github.com/catsystems/cats-logs.git
+cd cats-logs/log_parsing
+pip install -r requirements.txt
+python log_visualizer.py -i <path to input log> -o <path to output directory>

The script parses the log file and generates a self-contained HTML file containing all plots. It also generates raw and processed CSV files for each type of recorded value.

For more information about the visualizer script, run:

./log_visualizer.py --help

Common CLI Commands

The CLI is intended for advanced inspection, recovery, and configuration. To access it, connect the Vega through the Configurator and open CLI. The commands and parameters below are the most useful ones; run help for the authoritative list provided by the connected firmware. Square brackets [ ] indicate an optional argument, while angle brackets < > identify a parameter name.
After changing configuration values, run save and verify the result with config.

blPut the board into DFU modeFor advanced recovery. Normal firmware updates use the Configurator workflow in Chapter 6.
cdChange the current working directory
configPrint the flight config in a human-readable format
defaults [–no-outputs]Reset to default settingsThe default configuration triggers pyro channels. If –no-outputs is passed, pyro triggering is not configured.
dumpPrint configurable settings in a readable format
flash_eraseErase everything on the flash chip; this might take a while
flash_testTest writing to and reading from the flashFor testing purposes only; do not use
flash_start_writeStart writing to flashFor testing purposes only; do not use
flash_stop_writeStop writing to flashFor testing purposes only; do not use
flight_dump <flight_number>Print a specific flight in binary format
flight_parse <flight_number>Print a specific flight in a human-readable format
get [command_name]Get a variable value, described in Table 13
help [search string]Display all commands with a description
lfs_formatReformat the flash filesystem
log_enableEnable log output on the terminal
lsList all files in the current working directory
rebootReboot the flight computerThis command does not save the changed settings by itself
rec_infoGet information about flash usage
rm <file_name>Remove a file
saveSave flight configuration
set [<command_name>=<value>]Set a variable, described in Table 13
stats <flight_number>Print flight statistics
statusShow current sensor data, flight phase, and other important information
versionShow the firmware version
Table 11: Common CLI commands

Common Configuration Parameters

The variables below can be read with the get command or changed with the set command. Changes are saved to the flight computer’s configuration only after the save command is run.

acc_thresholdAcceleration threshold above which liftoff is detected
main_altitudeAltitude above ground level under which main deployment is triggered
timer1_startEvent which triggers timer 1
timer1_triggerEvent which is triggered once timer 1 elapses
timer1_durationTimer 1 duration
timer2_startEvent which triggers timer 2
timer2_triggerEvent which is triggered once timer 2 elapses
timer2_durationTimer 2 duration
timer3_startEvent which triggers timer 3
timer3_triggerEvent which is triggered once timer 3 elapses
timer3_durationTimer 3 duration
timer4_startEvent which triggers timer 4
timer4_triggerEvent which is triggered once timer 4 elapses
timer4_durationTimer 4 duration
ev_calibrateSet the actions associated with the calibration eventDo not use!
ev_readySet the actions associated with the ready eventDo not use!
ev_liftoffSet the actions associated with the liftoff eventPrefer the Configurator’s Events & Timers page.
ev_burnoutSet the actions associated with the burnout eventDo not use!
ev_apogeeSet the actions associated with the apogee eventDo not use!
ev_main_deploymentSet the actions associated with the main deployment eventDo not use!
ev_touchdownSet the actions associated with the touchdown eventDo not use!
ev_custom1Set the actions associated with the custom 1 eventDo not use!
ev_custom2Set the actions associated with the custom 2 eventDo not use!
servo1_init_posSet the initial position of servo 1
servo2_init_posSet the initial position of servo 2
tele_link_phraseSet the telemetry link phrase
tele_test_phraseSet the testing phrase
tele_power_levelSet the telemetry power level
tele_enableEnable or disable telemetry
tele_adaptive_powerEnable or disable adaptive power for the telemetry power levelAdaptive power mode boosts output power to maximum when the flight computer is in THRUSTING mode and returns it to the user-set value when TOUCHDOWN is registered.
buzzer_volumeSet the buzzer volume
battery_typeSet the battery type used with the CATS Vega
rec_elementsSet the desired recorded elementsA bit mask corresponding to the rec_entry_type_e enum
rec_speedSet the desired sampling period for recording
test_modeEnable or disable testing modeA reboot is required after saving the change.
Table 12: Common parameters used with the get and set commands

FAQ and Troubleshooting

The Configurator does not find my Vega
Use a USB data cable and connect the Vega directly to the computer. If more than one compatible device is connected, select the intended device manually. Use the refresh button in the device selector after reconnecting the cable. On Windows, also check whether another application has opened the same serial port.

My configuration changes disappear after reconnecting
Select Save before disconnecting or rebooting the Vega. After saving, use Refresh or reconnect and confirm that the stored values match the intended configuration. Run Preflight before flight.

The Ground Station does not receive telemetry
Confirm that telemetry is enabled on the Vega, both devices have antennas attached, and the Ground Station receiver mode and link phrase match the Vega configuration. In Single mode, Link Phrase 1 is used by both receivers; in Dual mode, each receiver has its own phrase. Check the Ground Station’s Firmware Versions page if only one receiver behaves unexpectedly.

Testing mode does not arm
Enable testing mode and set a valid testing phrase in the Configurator, save the configuration, and reboot the Vega. Set the same Test Phrase and receiver mode on the Ground Station. The Vega must emit the Testing beep pattern before the Ground Station can arm it. See Chapter 8 for the complete safety procedure.

A flight or Ground Station log is missing
Vega flight logs can be opened from the Configurator’s Flight Logs page, including logs still stored onboard. Ground Station logs are exposed on the CATS GS USB drive; finalize an active log before copying it, and use Settings → System → USB Drive before disconnecting the cable.

A firmware update was interrupted
Reconnect the device and start the update again using the recovery procedure in Chapter 6. After any update, reconnect and verify the reported version before using the device. Normal Vega firmware installation from the Configurator is supported on Windows.

GNSS position is unavailable or inaccurate
Move the Vega and Ground Station outdoors with a clear view of the sky, keep antennas away from large conductive objects, and allow time for a fix. Do not rely on the last displayed coordinates until the Ground Station shows a current fix.

If the problem remains, collect the device and firmware versions, describe the exact steps taken, and contact us on our Discord server or open an issue in the relevant CATS repository.

\ No newline at end of file diff --git a/docs/images/How To Use/Configurator/Configurator_Configuration.png b/docs/images/How To Use/Configurator/Configurator_Configuration.png new file mode 100644 index 00000000..8c03d88f Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Configuration.png differ diff --git a/docs/images/How To Use/Configurator/Configurator_Events_Timers.png b/docs/images/How To Use/Configurator/Configurator_Events_Timers.png new file mode 100644 index 00000000..a2cdfd32 Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Events_Timers.png differ diff --git a/docs/images/How To Use/Configurator/Configurator_Firmware_Updates.png b/docs/images/How To Use/Configurator/Configurator_Firmware_Updates.png new file mode 100644 index 00000000..15449c61 Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Firmware_Updates.png differ diff --git a/docs/images/How To Use/Configurator/Configurator_Flight_Logs.png b/docs/images/How To Use/Configurator/Configurator_Flight_Logs.png new file mode 100644 index 00000000..80be2840 Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Flight_Logs.png differ diff --git a/docs/images/How To Use/Configurator/Configurator_Preflight.png b/docs/images/How To Use/Configurator/Configurator_Preflight.png new file mode 100644 index 00000000..440b5724 Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Preflight.png differ diff --git a/docs/images/How To Use/Configurator/Configurator_Profiles.png b/docs/images/How To Use/Configurator/Configurator_Profiles.png new file mode 100644 index 00000000..07de5c5b Binary files /dev/null and b/docs/images/How To Use/Configurator/Configurator_Profiles.png differ diff --git a/docs/images/How To Use/Configurator/GUI_CLI.jpg b/docs/images/How To Use/Configurator/GUI_CLI.jpg deleted file mode 100644 index d95c62ee..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_CLI.jpg and /dev/null differ diff --git a/docs/images/How To Use/Configurator/GUI_Config.png b/docs/images/How To Use/Configurator/GUI_Config.png deleted file mode 100644 index b6cc082d..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_Config.png and /dev/null differ diff --git a/docs/images/How To Use/Configurator/GUI_EventSel.jpg b/docs/images/How To Use/Configurator/GUI_EventSel.jpg deleted file mode 100644 index 915654c5..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_EventSel.jpg and /dev/null differ diff --git a/docs/images/How To Use/Configurator/GUI_Events.jpg b/docs/images/How To Use/Configurator/GUI_Events.jpg deleted file mode 100644 index 2cbb0b1c..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_Events.jpg and /dev/null differ diff --git a/docs/images/How To Use/Configurator/GUI_Home.jpg b/docs/images/How To Use/Configurator/GUI_Home.jpg deleted file mode 100644 index 6b75486b..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_Home.jpg and /dev/null differ diff --git a/docs/images/How To Use/Configurator/GUI_Timers.jpg b/docs/images/How To Use/Configurator/GUI_Timers.jpg deleted file mode 100644 index 371ab4d9..00000000 Binary files a/docs/images/How To Use/Configurator/GUI_Timers.jpg and /dev/null differ diff --git a/docs/images/How To Use/Groundstation/GS_Data_Details.png b/docs/images/How To Use/Groundstation/GS_Data_Details.png new file mode 100644 index 00000000..35b3baa3 Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Data_Details.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Data_Logs.png b/docs/images/How To Use/Groundstation/GS_Data_Logs.png new file mode 100644 index 00000000..83cdbfcb Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Data_Logs.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Live_Downrange.png b/docs/images/How To Use/Groundstation/GS_Live_Downrange.png new file mode 100644 index 00000000..55aa219b Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Live_Downrange.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Live_Telemetry.png b/docs/images/How To Use/Groundstation/GS_Live_Telemetry.png new file mode 100644 index 00000000..2d31147d Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Live_Telemetry.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Main_Menu.png b/docs/images/How To Use/Groundstation/GS_Main_Menu.png new file mode 100644 index 00000000..10d912ca Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Main_Menu.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Recovery.png b/docs/images/How To Use/Groundstation/GS_Recovery.png new file mode 100644 index 00000000..b7d230f4 Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Recovery.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Recovery_QR.png b/docs/images/How To Use/Groundstation/GS_Recovery_QR.png new file mode 100644 index 00000000..3bee394c Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Recovery_QR.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Sensors_Orientation.png b/docs/images/How To Use/Groundstation/GS_Sensors_Orientation.png new file mode 100644 index 00000000..3704db00 Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Sensors_Orientation.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Sensors_Readings.png b/docs/images/How To Use/Groundstation/GS_Sensors_Readings.png new file mode 100644 index 00000000..e115663a Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Sensors_Readings.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Settings_Preferences.png b/docs/images/How To Use/Groundstation/GS_Settings_Preferences.png new file mode 100644 index 00000000..18382760 Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Settings_Preferences.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Settings_System.png b/docs/images/How To Use/Groundstation/GS_Settings_System.png new file mode 100644 index 00000000..f99dbeb0 Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Settings_System.png differ diff --git a/docs/images/How To Use/Groundstation/GS_Settings_Telemetry.png b/docs/images/How To Use/Groundstation/GS_Settings_Telemetry.png new file mode 100644 index 00000000..0ebe729e Binary files /dev/null and b/docs/images/How To Use/Groundstation/GS_Settings_Telemetry.png differ diff --git a/docs/images/How To Use/Groundstation/Ground_Station.jpg b/docs/images/How To Use/Groundstation/Ground_Station.jpg index ccbe2572..f72b86ec 100644 Binary files a/docs/images/How To Use/Groundstation/Ground_Station.jpg and b/docs/images/How To Use/Groundstation/Ground_Station.jpg differ diff --git a/docs/images/How To Use/Groundstation/Ground_Station_DFU.png b/docs/images/How To Use/Groundstation/Ground_Station_DFU.png deleted file mode 100644 index cbb2ab33..00000000 Binary files a/docs/images/How To Use/Groundstation/Ground_Station_DFU.png and /dev/null differ diff --git a/docs/images/How To Use/Groundstation/Ground_Station_Live_Data.jpg b/docs/images/How To Use/Groundstation/Ground_Station_Live_Data.jpg deleted file mode 100644 index ae1215bb..00000000 Binary files a/docs/images/How To Use/Groundstation/Ground_Station_Live_Data.jpg and /dev/null differ diff --git a/docs/images/How To Use/Groundstation/Ground_Station_Logs.png b/docs/images/How To Use/Groundstation/Ground_Station_Logs.png deleted file mode 100644 index 24cc2699..00000000 Binary files a/docs/images/How To Use/Groundstation/Ground_Station_Logs.png and /dev/null differ diff --git a/docs/images/How To Use/Software Update/Radio_Complete.png b/docs/images/How To Use/Software Update/Radio_Complete.png new file mode 100644 index 00000000..f62d35a9 Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_Complete.png differ diff --git a/docs/images/How To Use/Software Update/Radio_Confirm.png b/docs/images/How To Use/Software Update/Radio_Confirm.png new file mode 100644 index 00000000..2e78bbc0 Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_Confirm.png differ diff --git a/docs/images/How To Use/Software Update/Radio_File.png b/docs/images/How To Use/Software Update/Radio_File.png new file mode 100644 index 00000000..e14b85ef Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_File.png differ diff --git a/docs/images/How To Use/Software Update/Radio_Progress.png b/docs/images/How To Use/Software Update/Radio_Progress.png new file mode 100644 index 00000000..20534924 Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_Progress.png differ diff --git a/docs/images/How To Use/Software Update/Radio_Receivers.png b/docs/images/How To Use/Software Update/Radio_Receivers.png new file mode 100644 index 00000000..08d8d9b9 Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_Receivers.png differ diff --git a/docs/images/How To Use/Software Update/Radio_Settings.png b/docs/images/How To Use/Software Update/Radio_Settings.png new file mode 100644 index 00000000..b66a92a8 Binary files /dev/null and b/docs/images/How To Use/Software Update/Radio_Settings.png differ diff --git a/docs/images/Testing/GS_Testing_Confirm.png b/docs/images/Testing/GS_Testing_Confirm.png new file mode 100644 index 00000000..0336e870 Binary files /dev/null and b/docs/images/Testing/GS_Testing_Confirm.png differ diff --git a/docs/images/Testing/GS_Testing_Events.png b/docs/images/Testing/GS_Testing_Events.png new file mode 100644 index 00000000..04365bf8 Binary files /dev/null and b/docs/images/Testing/GS_Testing_Events.png differ diff --git a/docs/images/Testing/GS_Testing_ReadyToStart.png b/docs/images/Testing/GS_Testing_ReadyToStart.png new file mode 100644 index 00000000..706da308 Binary files /dev/null and b/docs/images/Testing/GS_Testing_ReadyToStart.png differ diff --git a/docs/images/Testing/GS_Testing_Safety.png b/docs/images/Testing/GS_Testing_Safety.png new file mode 100644 index 00000000..d5382b59 Binary files /dev/null and b/docs/images/Testing/GS_Testing_Safety.png differ diff --git a/docs/images/Testing/GS_Testing_Starting.png b/docs/images/Testing/GS_Testing_Starting.png new file mode 100644 index 00000000..7a510024 Binary files /dev/null and b/docs/images/Testing/GS_Testing_Starting.png differ diff --git a/docs/images/Testing/GroundStation_Arm_Testing_Mode.jpg b/docs/images/Testing/GroundStation_Arm_Testing_Mode.jpg deleted file mode 100644 index 35918636..00000000 Binary files a/docs/images/Testing/GroundStation_Arm_Testing_Mode.jpg and /dev/null differ diff --git a/docs/images/Testing/GroundStation_Event_Menu.jpg b/docs/images/Testing/GroundStation_Event_Menu.jpg deleted file mode 100644 index 18506dee..00000000 Binary files a/docs/images/Testing/GroundStation_Event_Menu.jpg and /dev/null differ diff --git a/docs/images/Testing/GroundStation_MainMenu.jpg b/docs/images/Testing/GroundStation_MainMenu.jpg deleted file mode 100644 index ccbe2572..00000000 Binary files a/docs/images/Testing/GroundStation_MainMenu.jpg and /dev/null differ diff --git a/docs/images/Testing/GroundStation_Trigger_Event.jpg b/docs/images/Testing/GroundStation_Trigger_Event.jpg deleted file mode 100644 index e6cd4540..00000000 Binary files a/docs/images/Testing/GroundStation_Trigger_Event.jpg and /dev/null differ diff --git a/docs/images/Testing/GroundStation_Wait_Testing_Mode.jpg b/docs/images/Testing/GroundStation_Wait_Testing_Mode.jpg deleted file mode 100644 index 100b2179..00000000 Binary files a/docs/images/Testing/GroundStation_Wait_Testing_Mode.jpg and /dev/null differ diff --git a/docs/styles.typ b/docs/styles.typ index ca0819d9..24e19af8 100644 --- a/docs/styles.typ +++ b/docs/styles.typ @@ -1,22 +1,72 @@ // Shared layout and semantic helpers for the CATS User Manual. +#let manual-last-updated = "18 September 2026" #let cats-orange = rgb("#f0870f") #let light-blue = rgb("#ddebf7") #let dark-blue = rgb("#1f4e78") #let light-red = rgb("#ffabab") #let dark-red = rgb("#800000") +#let web-image-root = "https://raw.githubusercontent.com/catsystems/cats-embedded/docs/web-manual/docs/images/" + +#let doc-image(path, width: auto, alt: "", outline: false) = context { + if target() == "html" { + let rendered = html.img( + src: web-image-root + path.replace(" ", "%20"), + alt: alt, + loading: "lazy", + decoding: "async", + ) + if outline { + html.elem( + "span", + attrs: ( + class: "manual-screen-outline", + style: "display:inline-block;line-height:0;border:1px solid color-mix(in srgb,currentColor 22%,transparent);border-radius:2px;overflow:hidden", + ), + rendered, + ) + } else { + rendered + } + } else { + if outline { + block( + width: width, + inset: 0pt, + radius: 1pt, + stroke: 0.5pt + luma(65%), + clip: true, + )[ + #image("images/" + path, width: 100%) + ] + } else { + image("images/" + path, width: width) + } + } +} + +#let source-note(url, label-name: none) = context { + if target() == "html" { + if label-name == none { metadata(none) } else { [#metadata(none) #label(label-name)] } + } else { + footnote[ + #if label-name != none { [#metadata(none) #label(label-name)] } + #link(url)[#url] + ] + } +} #let reference-numbers = ( - "fn:note1": "1", - "sec:VegaHW": "5.1", - "sec:FSM": "5.2.1", - "sec:DescriptionOfConfigurator": "5.3.2", - "sec:GeneratePlots": "5.3.7", - "sec:softwareupdates": "5.3.8", - "sec:BeepingPatterns": "5.4", - "sec:explanMenus": "6.2.1", - "sec:telemetrymode": "6.2.2", - "sec:data_streaming": "6.2.3", - "sec:gs_updates": "6.2.6", + "sec:VegaHW": "4.1", + "sec:FSM": "4.2.1", + "sec:DescriptionOfConfigurator": "4.3.2", + "sec:GeneratePlots": "4.3.7", + "sec:softwareupdates": "4.3.8", + "sec:BeepingPatterns": "4.4", + "sec:explanMenus": "5.2.1", + "sec:telemetrymode": "5.2.2", + "sec:data_streaming": "5.2.3", + "sec:gs_updates": "5.2.6", + "sec:FirmwareUpdates": "6", "sec:Examples": "7", "sec:Testing": "8", "sec:AdvancedInfo": "9", @@ -24,49 +74,26 @@ "sec:GeneratePlotsPython": "9.4", "sec:CLI": "9.5", "sec:FAQ": "10", - "tab:RevHist": "1", - "tab:Specs": "2", - "tab:FSMTransitions": "3", - "tab:ActionTable": "4", - "tab:HomeTabOverview": "5", - "tab:ConfigurationTabOverview": "6", - "tab:HowToAct": "7", - "tab:BeepingPatternsStates": "8", - "tab:BeepingPatternsErrors": "9", - "tab:GSSpecs": "10", - "tab:CLICommands": "11", - "tab:CLICommandsSetGet": "12", + "tab:Specs": "1", + "tab:FSMTransitions": "2", + "tab:ActionTable": "3", + "tab:ConfiguratorNavigation": "4", + "tab:HowToAct": "5", + "tab:BeepingPatternsStates": "6", + "tab:BeepingPatternsErrors": "7", + "tab:GSSpecs": "8", + "tab:GSSettings": "9", + "tab:ExampleSimple": "10", + "tab:ExampleAdvanced": "11", + "tab:CLICommands": "12", + "tab:CLICommandsSetGet": "13", "fig:VegaHWSpecs": "2", "fig:FSM": "3", - "fig:GUIHome": "4", - "fig:GUIConfig": "5", - "fig:GUIEvents": "6", - "fig:GUIEventSel": "7", - "fig:GUITimers": "8", - "fig:GUICLI": "9", - "fig:SWUpdateInit": "12a", - "fig:SWUpdateUSB": "12b", - "fig:SWUpdateConnected": "12c", - "fig:SWUpdateProgram": "12d", - "fig:SWUpdateProgramFinished": "12e", - "fig:SWUpdate": "12", - "fig:HWsimpleExample": "18", - "fig:ExampleSimpleConfig": "19a", - "fig:ExampleSimpleEvents": "19b", - "fig:ExampleSimpleTimers": "19c", - "fig:ExampleSimple": "19", - "fig:HWadvancedExample": "20", - "fig:ExampleAdvancedConfig": "21a", - "fig:ExampleAdvancedEvents": "21b", - "fig:ExampleAdvancedTimers": "21c", - "fig:ExampleAdvanced": "21", - "fig:GSTestingMainMenu": "22", - "fig:GSTestingArming": "23", - "fig:GSTestingWaitingArming": "24", - "fig:GSTestingEventMenu": "25", - "fig:GSTestingEventTriggering": "26", - "fig:SoftwareOverview": "27", - "fig:fhss": "28", + "fig:RadioUpdateSequence": "19", + "fig:HWsimpleExample": "20", + "fig:HWadvancedExample": "21", + "fig:SoftwareOverview": "24", + "fig:fhss": "25", ) #let glossary-names = ( @@ -140,10 +167,11 @@ #let gls(key, cap: false) = { let value = glossary-names.at(key, default: [#key]) metadata(("glossary-use", key)) - link(glossary-labels.at(key))[#if cap { upper(value.slice(0, 1)) + value.slice(1) } else { value }] + if cap { upper(value.slice(0, 1)) + value.slice(1) } else { value } } #let glossary-pages(key) = context { + if target() == "html" { return none } let uses = query(metadata).filter(item => item.value == ("glossary-use", key)) let pages = uses.map(item => (counter(page).at(item.location()).first(), item.location())) let unique = pages.fold((), (acc, pair) => { @@ -153,7 +181,7 @@ h(0.35em) unique.enumerate().map(pair => { if pair.first() > 0 { text(", ") } - link(pair.last().last())[#str(pair.last().first())] + str(pair.last().first()) }).join() } } @@ -166,71 +194,158 @@ strong(box(entry.at(1))), [#(entry.at(2)).#glossary-pages(entry.at(0))], )).flatten() - table( - columns: (2.7cm, 1fr), - column-gutter: 6pt, - row-gutter: row-gap, - inset: 0pt, - stroke: none, - align: (left + top, left + top), - ..cells, - ) + if target() == "html" { + html.elem("dl", attrs: (class: "glossary"))[ + #for entry in visible { + html.elem("dt", entry.at(1)) + html.elem("dd", entry.at(2)) + } + ] + } else { + table( + columns: (2.7cm, 1fr), + column-gutter: 6pt, + row-gutter: row-gap, + inset: 0pt, + stroke: none, + align: (left + top, left + top), + ..cells, + ) + } } -#let note(body) = block( - width: 100%, - inset: 10pt, - radius: 6pt, - fill: light-blue, - stroke: 1.5pt + dark-blue, - above: 8pt, - below: 8pt, - body, -) +#let note(body) = context { + if target() == "html" { + html.elem("aside", attrs: (class: "notice note"), body) + } else { + block( + width: 100%, + inset: 10pt, + radius: 6pt, + fill: light-blue, + stroke: 1.5pt + dark-blue, + above: 8pt, + below: 8pt, + body, + ) + } +} -#let warning(body) = block( - width: 100%, - inset: 10pt, - radius: 6pt, - fill: light-red, - stroke: 1.5pt + dark-red, - above: 8pt, - below: 8pt, - body, -) +#let warning(body) = context { + if target() == "html" { + html.elem("aside", attrs: (class: "notice warning"), body) + } else { + block( + width: 100%, + inset: 10pt, + radius: 6pt, + fill: light-red, + stroke: 1.5pt + dark-red, + above: 8pt, + below: 8pt, + body, + ) + } +} #let figure-counter = counter("cats-figure") #let table-counter = counter("cats-table") -#let cats-figure(body, caption: none, continued: false) = { +#let cats-figure(body, caption: none, continued: false, breakable: false) = { if not continued { figure-counter.step() } - block(width: 100%, breakable: false, above: 8pt, below: 8pt)[ - #align(center, body) - #if caption != none { - v(5pt) - align(center)[#text(size: 8pt)[Figure #context figure-counter.display(): #caption]] + context { + if target() == "html" { + html.elem("figure", attrs: (class: "manual-figure"))[ + #body + #if caption != none { + html.elem("figcaption")[Figure #figure-counter.display(): #caption] + } + ] + } else { + block(width: 100%, breakable: breakable, above: 8pt, below: 8pt)[ + #align(center, body) + #if caption != none { + v(5pt) + align(center)[#text(size: 8pt)[Figure #context figure-counter.display(): #caption]] + } + ] } - ] + } } -#let cats-table(body, caption: none, continued: false, breakable: false) = { +#let cats-table(body, caption: none, continued: false, breakable: false, class-name: none) = { if not continued { table-counter.step() } - block(width: 100%, breakable: breakable, above: 7pt, below: 7pt)[ - #set par(justify: false, leading: 0.5em, spacing: 0.8em) - #set text(hyphenate: false) - #body - #if caption != none { - v(4pt) - align(center)[#text(size: 8pt)[Table #context table-counter.display(): #caption]] + context { + if target() == "html" { + let classes = if class-name == none { "manual-table" } else { "manual-table " + class-name } + html.elem("figure", attrs: (class: classes))[ + #body + #if caption != none { + html.elem("figcaption")[Table #table-counter.display(): #caption] + } + ] + } else { + block(width: 100%, breakable: breakable, above: 7pt, below: 7pt)[ + #set par(justify: false, leading: 0.5em, spacing: 0.8em) + #set text(hyphenate: false) + #body + #if caption != none { + v(4pt) + align(center)[#text(size: 8pt)[Table #context table-counter.display(): #caption]] + } + ] } - ] + } } -#let subfigure(body, caption, letter) = block(width: 100%)[ - #align(center, body) - #v(3pt) - #align(center)[#text(size: 8pt)[(#letter) #caption]] -] +#let subfigure(body, caption, letter, width: 100%, label-name: none) = context { + let result = if target() == "html" { + html.elem("figure", attrs: (class: "manual-subfigure"))[ + #body + #html.elem("figcaption")[(#letter) #caption] + ] + } else { + align(center)[#block(width: width)[ + #align(center, body) + #v(3pt) + #align(center)[#text(size: 8pt)[(#letter) #caption]] + ]] + } + if label-name == none { + result + } else { + [#result #label(label-name)] + } +} + +#let responsive-split(left, right, columns: (63%, 1fr, 33%)) = context { + if target() == "html" { + html.elem("div", attrs: (class: "responsive-split"))[ + #html.elem("div")[#left] + #html.elem("div")[#right] + ] + } else { + grid(columns: columns, left, [], right) + } +} + +#let figure-stack(spacing: 8pt, breakable: false, ..children) = context { + let items = children.pos() + if target() == "html" { + html.elem("div", attrs: (class: "figure-stack"))[ + #for item in items { html.elem("div", item) } + ] + } else if breakable { + block(width: 100%, breakable: true)[ + #for (index, item) in items.enumerate() { + if index > 0 { v(spacing) } + block(width: 100%, breakable: false, item) + } + ] + } else { + stack(dir: ttb, spacing: spacing, ..items) + } +} #let normal-header = context { set par(spacing: 1.65em)