Release v3.5.0

[LeStarch]

The release v3.5.0 contains a number of improvements. Primarily, the Operating System Abstraction Layer (OSAL) has been refactored to make integration with new operating systems easier. It also ensures that the OSAL selection for each subsystem is independent, and selected per-executable rather than the entire project.

Breaking Changes

There are a number of breaking changes in this release. Users will need to fix these issues when upgrading from v3.4.3.

Configuration Changes

Configuration has been substantially changed. Users should migrate to the new FpConfig.h available in fprime/config and adjust settings accordingly.

General OSAL Changes

Users are encouraged to call Os::init() in the main function of their deployment. While not strictly necessary, this initializes OS singletons at a deterministic time.

Fw::Logger::log calls that precede this call will not be output.

#include <Os/Os.hpp>
...
int main(...) {
    Os::init();
    ...
}

Failing to do so will result in singletons self-initializing on first usage resulting in a very small delay on first usage. Fw::Logger::log messages will not use the Os::Console output until Os::init() is called.

FPP Changes

FPP has introduced new keywords to support integrated state machines! This means users who chose those names will need to escape them. Commonly, state is used and should be escaped as $state

- event SetBlinkingState(state: Fw.On) ...
+ event SetBlinkingState($state: Fw.On) ...

Task Changes

Most components have standardized on start, stop, and join calls to manage internal tasks. To start these tasks users should switch to the new start, stop, and join methods.

-    comm.startSocketTask(name, true, COMM_PRIORITY, Default::STACK_SIZE);
+    comm.start(name, true, COMM_PRIORITY, Default::STACK_SIZE);
...

-    comm.stopSocketTask();
-    (void)comm.joinSocketTask(nullptr);
+    comm.join();
+   comm.stop();

Fully Qualified Instance Names

Instances in F Prime dictionaries and typologies are now fully-qualified. This means that the instances are prepended with the module names. To restore the global-instance functionality of older deployments, please remove modules definitions from around instances.

- module Ref {
...

  instance blockDrv: Drv.BlockDriver base id 0x0100 \
    queue size Default.QUEUE_SIZE \
    stack size Default.STACK_SIZE \
    priority 140
...
- }

StringUtils Changes

Users of StringUtils functions should now supply a FwSizeType and may no longer use U32 as arguments.

Linux GPIO driver

Users of the LinuxGpioDriver now should exepct a return value of Drv::GpioStatus from read and write calls. Additionally, the open call now expects a chip argument.

- bool gpio_success = gpioDriver.open(13, Drv::LinuxGpioDriver::GpioDirection::GPIO_OUT);
+ Os::File::Status gpio_success = gpioDriver.open("/dev/gpiochip0", 13, Drv::LinuxGpioDriver::GpioConfiguration::GPIO_OUTPUT);

Time and Interval Changes

Users should now supply a Fw::TimeInterval(seconds, microseconds) to calls to Os::Task::delay. Svc.TimeVal has been replaced by Os::RawTime.

Full List of Changes

• Fixed UT by @SMorettini in Fixed UT #2543
• Issue 2457 by @LeStarch in Issue 2457 #2502
• Address comments from Data product framework support #2485 by @bocchino in Address comments from #2485 #2542
• Update File.cpp by @LeStarch in Update File.cpp #2555
• Add shadow variable and pedantic warnings by @JohanBertrand in Add shadow variable and pedantic warnings #2544
• Add DpManager by @bocchino in Add DpManager #2546
• Update troubleshooting by @thomas-bc in Update troubleshooting #2561
• Fixed documentation of U32 (Swapped signed and unsigned int) by @tsha-256 in Fixed documentation of U32 (Swapped signed and unsigned int) #2559
• Resolve string_copy static analysis warnings by @thomas-bc in Resolve string_copy static analysis warnings #2556
• Add Fw::ObjectName to hold Fw::ObjBase name by @thomas-bc in Add Fw::ObjectName to hold Fw::ObjBase name #2497
• Remove FPP dependencies on native int types by @bocchino in Remove FPP dependencies on native int types #2548
• Force pip to upgrade during setup action by @thomas-bc in Force pip to upgrade during setup action #2565
• Explicity add test dependencies to Os_ut_exe by @LeStarch in Explicity add test dependencies to Os_ut_exe #2569
• Fix data product array record size by @bocchino in Fix data product array record size #2568
• Adding GDS development guide by @LeStarch in Adding GDS development guide #2577
• Update dictionary JSON spec field names and examples by @jwest115 in Update dictionary JSON spec field names and examples #2574
• Fix crosscompiler path in tutorial by @thomas-bc in Fix crosscompiler path in tutorial #2599
• Fix broken links in INSTALL.md by @thomas-bc in Fix broken links in INSTALL.md #2610
• Fixes fprime-util generate fails with cmake 3.16.3 #2602; bumps required version to 3.16 by @LeStarch in Fixes #2602; bumps required version to 3.16 #2617
• Update Svc/PolyDb to use configurable FPP enumeration as index by @timcanham in Update Svc/PolyDb to use configurable FPP enumeration as index #2587
• Disambiguate fpp error messages. Fixes: Run CMake UT CI On Minimum Required CMake Version #2618 by @LeStarch in Disambiguate fpp error messages. Fixes: #2618 #2620
• Add Java requirement to install guide by @LeStarch in Add Java requirement to install guide #2621
• Produce error on restricted targets. Fixes: fprime-util generate displays generic error when library is missing target restrictions #2486 by @LeStarch in Produce error on restricted targets. Fixes: #2486 #2633
• Fix missing fpp_depend build. Fixes: Adding a file to config directory causes FPP "symbol not found error" #2576 by @LeStarch in Fix missing fpp_depend build. Fixes: #2576 #2631
• Removing GroundInterface component. Fixes: Remove Ground Interface #2037 by @LeStarch in Removing GroundInterface component. Fixes: #2037 #2632
• Split CMake tests and run with minimum cmake by @LeStarch in Split CMake tests and run with minimum cmake #2619
• Add DpWriter by @bocchino in Add DpWriter #2593
• Fix INI newline processing. Fixes Diagnose Strange Text #2630 by @LeStarch in Fix INI newline processing. Fixes #2630 #2637
• Correcting rate group documentation. Fixes Rate group documentation inaccurate #1719 by @LeStarch in Correcting rate group documentation. Fixes #1719 #2638
• Issue 1604 by @LeStarch in Issue 1604 #2625
• Fixing Documentation Generation fo macOS by @LeStarch in Fixing Documentation Generation fo macOS #2655
• Adding start apps and arguments by @LeStarch in Adding start apps and arguments #2616
• Initial documentation of fprime libraries by @LeStarch in Initial documentation of fprime libraries #2665
• More GDS plugin guide improvements by @LeStarch in More GDS plugin guide improvements #2670
• Revise types in generated C++ code by @bocchino in Revise types in generated C++ code #2668
• Add CODE_OF_CONDUCT.md by @LeStarch in Add CODE_OF_CONDUCT.md #2629
• Update JSON Dictionary spec by @thomas-bc in Update JSON Dictionary spec #2663
• Format cpp and hpp files in Fw/Types by @bocchino in Format cpp and hpp files in Fw/Types #2677
• FPP v2.1.0a7 by @bocchino in FPP v2.1.0a7 #2676
• Revising integration test api. Fixes: Documentation: Rewrite Integration and Test Guide #1902 by @LeStarch in Revising integration test api. Fixes: #1902 #2652
• trouble-shooting-guide-2500 by @rlcheng in trouble-shooting-guide-2500 #2684
• Trouble shooting guide 2500 by @rlcheng in Trouble shooting guide 2500 #2698
• Improve error display on failure by @JohanBertrand in Improve error display on failure #2696
• feat(ci): add markdown link checker by @SauravMaheshkar in feat(ci): add markdown link checker #2651
• code clean up for POSIX. by @kevin-f-ortega in code clean up for POSIX. #2700
• Add JSON dictionary generation to CMake system by @thomas-bc in Add JSON dictionary generation to CMake system #2598
• Add Fw::ExternalString and revise string implementations by @bocchino in Add Fw::ExternalString and revise string implementations #2679
• Data Product Catalog prototype by @timcanham in Data Product Catalog prototype #2667
• Fix string records for data products by @bocchino in Fix string records for data products #2697
• Add log on TCP/UDP UT failure and fix UDP UT by @JohanBertrand in Add log on TCP/UDP UT failure and fix UDP UT #2705
• Fixed conversion warnings on framework tests by @JohanBertrand in Fixed conversion warnings on framework tests #2606
• Create TickDriver interface by @chownw in Create TickDriver interface #2708
• Make single-argument string constructors explicit by @bocchino in Make single-argument string constructors explicit #2707
• Fix copying of data product containers by @bocchino in Fix copying of data product containers #2711
• Update of clang tidy checks by @JohanBertrand in Update of clang tidy checks #2710
• Fix Typo by @inferenceus in Fix Typo #2716
• Renamed Time Interface File and fixed where it's included by @CombustableLem0n in Renamed Time Interface File and fixed where it's included #2728
• Add contributing tips by @JohanBertrand in Add contributing tips #2704
• fixed typo by @konerzajakub in fixed typo #2736
• Add -Wno-format-truncation to root project by @thomas-bc in Add -Wno-format-truncation to root project #2719
• Os task refactor issue 2526 by @LeStarch in Os task refactor issue 2526 #2672
• Fixing port selection in TCP UTs by @LeStarch in Fixing port selection in TCP UTs #2739
• Work/string search by @timcanham in Work/string search #2720
• Remove dead link to kitware blog by @LeStarch in Remove dead link to kitware blog #2746
• Fix CI bash script for macOS by @JohanBertrand in Fix CI bash script for macOS #2742
• Create Command Interface by @rmzmrnn in Create Command Interface #2753
• Add Events FPP interface by @menaman123 in Add Events FPP interface #2749
• refactored FW_OBJ_NAME, FW_QUEUE_NAME, and FW_TASK_NAME. by @rldettloff in refactored FW_OBJ_NAME, FW_QUEUE_NAME, and FW_TASK_NAME. #2751
• Update FPP to v2.1.0a11 by @bocchino in Update FPP to v2.1.0a11 #2745
• Interface from LinuxSpiDriver by @menaman123 in Interface from LinuxSpiDriver #2762
• modified: Drv/TcpClient/TcpClientComponentImpl.cpp by @menaman123 in modified: Drv/TcpClient/TcpClientComponentImpl.cpp #2759
• Added Channel Interface for Telemetry by @menaman123 in Added Channel Interface for Telemetry #2757
• Fixed copy-paste typos. Should be UDP and not TCP. by @kevin-f-ortega in Fixed copy-paste typos. Should be UDP and not TCP. #2778
• feat: Add prepend flag to autocode register macro by @mosa11aei in feat: Add prepend flag to autocode register macro #2777
• Update upcoming events by @LeStarch in Update upcoming events #2767
• Add hyperlinks to Upcoming Events by @thomas-bc in Add hyperlinks to Upcoming Events #2787
• Change TCPServer backlog to 1 by @Lex-ari in Change TCPServer backlog to 1 #2785
• Add capability for removing sources after an autocoder by @mosa11aei in Add capability for removing sources after an autocoder #2786
• Diatixis Method Reorginization for Documentation by @GavinKnudsen in Diatixis Method Reorginization for Documentation #2717
• Add SmallSat Tutorial to upcoming events by @thomas-bc in Add SmallSat Tutorial to upcoming events #2789
• Ignore all HTTP links in Markdown link check by @thomas-bc in Ignore all HTTP links in Markdown link check #2793
• Rename EventsInterface to EventInterface by @thomas-bc in Rename EventsInterface to EventInterface #2792
• FPP v2.1.0a12 by @bocchino in FPP v2.1.0a12 #2795
• Match markdown of Channels with that of Events by @SiboVG in Match markdown of Channels with that of Events #2804
• Add Svc.Version component by @Shivaly-Reddy in Add Svc.Version component #2747
• Add Hub-Pattern Documentation by @Lex-ari in Add Hub-Pattern Documentation #2791
• Revise file name string sizes in AssertFatalAdapter events by @bocchino in Revise file name string sizes in AssertFatalAdapter events #2796
• Make _fprime_packages a folder where all libraries can live by @mosa11aei in Make _fprime_packages a folder where all libraries can live #2812
• Add phase config code to Ref. fprime-bootstrap Does Not Contain Phase Configuration Code #2820 by @LeStarch in Add phase config code to Ref. #2820 #2821
• Delete RPI legacy Topology.cpp and Components.hpp by @LeStarch in Delete RPI legacy Topology.cpp and Components.hpp #2822
• docs: Add AC pre-processor pattern to docs by @mosa11aei in docs: Add AC pre-processor pattern to docs #2808
• docs: Add documentation for F' subtopologies by @mosa11aei in docs: Add documentation for F' subtopologies #2743
• Refactor OS::Mutex in CMake selection by @thomas-bc in Refactor OS::Mutex in CMake selection #2790
• FPP v2.1.0 by @bocchino in FPP v2.1.0 #2811
• Implements Refactor Os::Log into CMake Selection #2723: Adds Os::Console to replace Os::Log by @LeStarch in Implements #2723: Adds Os::Console to replace Os::Log #2831
• Fix double-promotion in fprime codebase by @JohanBertrand in Fix double-promotion in fprime codebase #2818
• Updated troubleshooting md by @mprather in Updated troubleshooting md #2843
• Update CI to use Json dictionaries by @Lex-ari in Update CI to use Json dictionaries #2806
• Adding fflush call to posix console by @LeStarch in Adding fflush call to posix console #2857
• Fix Random UT Failure: PosixFile (Random UT Failure: PosixFile #2835) by @rlcheng in Fix Random UT Failure: PosixFile (#2835) #2860
• Update Ref and RPI for compatibility with FPP GDS decoding ENUM events incorrectly #349 (fully qualified component instance names) by @jwest115 in Update Ref and RPI for compatibility with FPP #349 (fully qualified component instance names) #2823
• Add sequence dispatcher component by @zimri-leisher in Add sequence dispatcher component #2731
• Remove versions from SystemResources and updates to Version component by @Shivaly-Reddy in Remove versions from SystemResources and updates to Version component #2866
• Improvement of Doxycomments in the CCSDS FDP checksum class by @JackNWhite in Improvement of Doxycomments in the CCSDS FDP checksum class #2855
• Fix ComQueue Does Not Deallocate Buffers on Overflow by @DJKessler in Fix ComQueue Does Not Deallocate Buffers on Overflow #2853
• Fix random UT failures on PosixFile by @rlcheng in Fix random UT failures on PosixFile #2862
• Phase 1 state machines by @garthwatney in Phase 1 state machines #2829
• Adding FppTest for overflow: drop, assert, hook by @LeStarch in Adding FppTest for overflow: drop, assert, hook #2842
• Fix paths in Cross Compiling Tutorial by @kevin-f-ortega in Fix paths in Cross Compiling Tutorial #2885
• Upgrade GitHub Actions ahead of NodeJS deprecation by @thomas-bc in Upgrade GitHub Actions ahead of NodeJS deprecation #2890
• Removing component init() functions where unneeded by @LeStarch in Removing component init() functions where unneeded #2893
• Fixing string_utils types to FwSizeType by @LeStarch in Fixing string_utils types to FwSizeType #2884
• Add Open Port Request on Sending Side of IpSocket by @csmith608 in Add Open Port Request on Sending Side of IpSocket #2683
• Fix Os::Console singleton to be heapless by @LeStarch in Fix Os::Console singleton to be heapless #2896
• Refactor Os::FileSystem and Os::Directory by @thomas-bc in Refactor Os::FileSystem and Os::Directory #2871
• Refactor Os::Queue into CMake selection by @LeStarch in Refactor Os::Queue into CMake selection #2895
• FP-2784: define trace id type by @Shivaly-Reddy in FP-2784: define trace id type #2917
• Fix warnings in tcp/udp UT by @JohanBertrand in Fix warnings in tcp/udp UT #2744
• Set assert size constant by @DJKessler in Set assert size constant #2921
• Issue Refactor Os::SystemResources into CMake Selection #2727: Refactor System Resources OSAL Implmentation by @LeStarch in Issue #2727: Refactor System Resources OSAL Implmentation  #2922
• Update FPP version to v2.2.0 by @bocchino in Update FPP version to v2.2.0 #2932
• OSAL clean-up by @LeStarch in OSAL clean-up #2933
• Make CI fast again! by @LeStarch in Make CI fast again! #2937
• Fixed F' C header files to be C++ compliant. by @bdshenker in Fixed F' C header files to be C++ compliant. #2936
• Random UT Failure: PosixFile by @rlcheng in Random UT Failure: PosixFile #2939
• Fix issues with DpContainer and ExternalSerializeBuffer by @bocchino in Fix issues with DpContainer and ExternalSerializeBuffer #2941
• Add Os::RawTime OSAL implementation, refactor Os::IntervalTimer by @thomas-bc in Add Os::RawTime OSAL implementation, refactor Os::IntervalTimer #2923
• Improved Linux GPIO Driver Using Chardev by @LeStarch in Improved Linux GPIO Driver Using Chardev #2943
• Add OSAL singleton initialization to Os::init() by @thomas-bc in Add OSAL singleton initialization to Os::init() #2947
• Add Os::Queue FPP models by @thomas-bc in Add Os::Queue FPP models #2948
• Bump Tools and GDS requirements to v3.5.0a1 by @thomas-bc in Bump Tools and GDS requirements to v3.5.0a1 #2949
• Fix Jekyll docs build error from curly braces interpretation by @thomas-bc in Fix Jekyll docs build error from curly braces interpretation #2951
• Update requirements.txt for release v3.5.0 by @thomas-bc in Update requirements.txt for release v3.5.0 #2952
• Correcting shutdown/close usage; refactoring TcpServer by @LeStarch in Correcting shutdown/close usage; refactoring TcpServer #2950
• Making Os::Task::delay use the singleton pattern by @LeStarch in Making Os::Task::delay use the singleton pattern #2954

New Contributors

• @tsha-256 made their first contribution in Fixed documentation of U32 (Swapped signed and unsigned int) #2559
• @rlcheng made their first contribution in trouble-shooting-guide-2500 #2684
• @SauravMaheshkar made their first contribution in feat(ci): add markdown link checker #2651
• @chownw made their first contribution in Create TickDriver interface #2708
• @inferenceus made their first contribution in Fix Typo #2716
• @CombustableLem0n made their first contribution in Renamed Time Interface File and fixed where it's included #2728
• @konerzajakub made their first contribution in fixed typo #2736
• @rmzmrnn made their first contribution in Create Command Interface #2753
• @menaman123 made their first contribution in Add Events FPP interface #2749
• @rldettloff made their first contribution in refactored FW_OBJ_NAME, FW_QUEUE_NAME, and FW_TASK_NAME. #2751
• @mosa11aei made their first contribution in feat: Add prepend flag to autocode register macro #2777
• @Lex-ari made their first contribution in Change TCPServer backlog to 1 #2785
• @GavinKnudsen made their first contribution in Diatixis Method Reorginization for Documentation #2717
• @SiboVG made their first contribution in Match markdown of Channels with that of Events #2804
• @Shivaly-Reddy made their first contribution in Add Svc.Version component #2747
• @mprather made their first contribution in Updated troubleshooting md #2843
• @zimri-leisher made their first contribution in Add sequence dispatcher component #2731
• @DJKessler made their first contribution in Fix ComQueue Does Not Deallocate Buffers on Overflow #2853
• @garthwatney made their first contribution in Phase 1 state machines #2829
• @bdshenker made their first contribution in Fixed F' C header files to be C++ compliant. #2936

Full Changelog: v3.4.3...v3.5.0

---

This discussion was created from the release Release v3.5.0.

[keck-in-space]

Is there any guidance on how one might upgrade from their current version of F Prime to the new version? We're on 3.4.2 and would like to upgrade to the 3.5.x series.

[zimri-leisher]

Sounds good! That way you also will get the new autocoded state machines, which are super exciting and useful!

[keck-in-space]

I've heard a little about these, but I haven't been able to find any documentation. Is there any yet? Very excited!

[LeStarch]

FPP packet support is expected in v3.7.0 (targeting May).

State machines are slated for v3.6.0 (early February).

[LeStarch]

Here is the super detailed state machine document: https://nasa.github.io/fpp/fpp-spec.html#Definitions_State-Machine-Definitions

[bocchino]

That citation is to the spec, which has all the details for implementers. You may want to consult the User's Guide first: https://nasa.github.io/fpp/fpp-users-guide.html#Defining-State-Machines. It's written more for users.