Flightkit Component Type Layout Reference
A guide to the structure and on-disk layout of Flightkit component types.
1. Introduction
Component types are the main structures that enable code reusability within
Flightkit. To provide this reusability they have a strictly defined structure.
They are described in componentType.xml files which have a fixed schema. In
this document we describe the main features of that schema. We also describe
the on-disk file structure which component types have.
2. Component Type XML
The following command is used to generate a component type XML for defining a new component type:
hfk component-type create package.ComponentNameThis command generates a file structure in library/component_types containing
a skeleton componentType.xml file according to the dot separated name
provided, which in this case was package.ComponentName:
Workspace
└──library
└── component_types
└── package
└── ComponentName
└── componentType.xmlThe skeleton file contains the bare minimum elements necessary to generate a
component type, those being <ModelElement>, and its child, <ComponentType>.
Without making any changes to the file, the component type that the XML defines,
package.ComponentName, can then be generated by executing the following
command:
hfk component-type generate package.ComponentNameThis generates various additional files for implementing the component type, resulting in the following file structure:
Workspace
├──generated
| └── ...
└──library
└── component_types
└── package
└── ComponentName
├── include
| ├── container
| | ├── ComponentName_Container_package.h
| | └── ComponentName_Container.h
| ├── type
| | └── ComponentName_prototypes.h
| ├── ComponentName_config.h
| └── ComponentName.h
├── test
| ├── lib_config
| | └── meson.build
| ├── meson.build
| └── ComponentName_Test.c
├── componentType.xml
├── meson.build
└── ComponentName.cNotice that the details of the directories under generated have been
excluded from the diagram. They are not important from the perspective of the
user. They are generated by the tooling and are required for the component to
build and operate as expected, however they are not ever intended to be viewed
or modified. For this reason they will not be discussed for the remainder of
this feature guide.
The file structure shown is the most basic file structure a component type must
have for it to be used within Flightkit. A component type in this form can be
instantiated in a deployment type, and its code executed as part of a mission.
It will not, however, provide any useful functionality. To add useful
functionality its componentType.xml file must be updated.
Functionality is added by including additional XML elements in the
componentType.xml file describing the desired behaviour. Once added, the
component type can be regenerated, and the tooling will update or add files
to include the necessary code for implementing the new functionality. The
majority of the auto-generated code does not require any modification by
the user. The few parts that do are clearly marked with TODOs indicating
exactly what the user must do to complete the implementation.
The following table indicates which user-facing files are updated or added following the inclusion of each XML element. It also illustrates the order in which the elements must be defined within the XML file to adhere to the tooling’s requirements. Note that some of the files listed in the table only receive small changes, such as adding an include path to make specific symbols accessible within that file, however we have still included them for completeness.
| Element | Files |
|---|---|
|
|
|
|
|
No effect on user-facing files. Determines which board is used when the component type is built. |
|
No effect on user-facing files. Determines which OSAL is used when the component type is built. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In addition to knowing which files are impacted by the XML, it is also useful to have a general understanding of their contents. The table below provides a basic description for each user-facing file that may exist within a component type’s file structure depending on its functionality.
| File | Description |
|---|---|
|
Defines symbols for uniquely identifying each of the component type’s exceptions. |
|
Defines symbols for uniquely identifying each of the component type’s events. |
|
Defines symbols for the component type’s custom data types. |
|
Declares functions for serialising and deserialising the component type’s custom data types. |
|
Defines symbols related to the component type’s provided services. |
|
Declares functions for transmitting requests via the component type’s required services. |
|
Defines symbols related to the component type’s required services, and declares functions for mocking the service during unit tests. |
|
Declares functions for initialising, finalising and handling transmission of data via the component type’s brokered services. |
|
Declares functions for initialising, finalising and publishing of data via the component type’s published services. |
|
Defines symbols for uniquely identifying each of the component type’s actions. |
|
Defines symbols for uniquely identifying each of the component type’s parameters. |
|
Defines symbols for accessing various members of the component type within the container, and declares functions for updating its state. |
|
Defines the structure of the component type’s container, defines symbols for accessing various members within the container, and declares functions for initialising and finalising the container, and handling its tasks. |
|
Declares functions for initialising and finalising the component type, and handling all of its generated functionality, as specified in its XML. |
|
Defines symbols for configuring the behaviour of the component type, which can be overwritten at build time. |
|
This file serves as the public interface to the component type. It defines its structure, and includes |
|
The main implementation file for the component type. Implements functions for initialising and finalising the component type, and handling all of its generated functionality, as per its XML. |
|
A skeleton version of |
|
Implements unit tests for the component type. |
|
A skeleton version of |
|
Defines symbols which are required by the build system to build the component type. |
|
Defines symbols which required by the build system to build the unit tests for the component type. |
|
Enables users to define custom compiler args when building the unit tests for the component type. |
As mentioned earlier, the majority of these files are not intended to be modified by the user. If a user makes changes to these particular files, and the component type is later regenerated, the tooling will overwrite the user’s changes with the file contents that it knows to be correct. For this reason, it is important that users only modify files that are intended to be modified.
Files which are intended to be modified include those which contain configurable values, or those that require additional user input to fully implement the code. These particular files do not get overwritten by the tooling when regenerating the component type. Instead, either a template file is generated to indicate the changes that the user must apply to the original file, or nothing additional is generated at all.
The following table indicates which user-facing files are overwritten by the tooling when regenerating a component type, and which are not. For those that are not, it also specifies which additional files are generated, if any, to indicate the changes that need to be manually applied to the original file.
| File | Overwrite Behaviour |
|---|---|
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Always overwritten |
|
Not overwritten, no additional file generated |
|
Not overwritten, no additional file generated |
|
Not overwritten, |
|
Always overwritten |
|
Not overwritten, |
|
Always overwritten |
|
Not overwritten, no additional file generated |
|
Not overwritten, no additional file generated |
|
Not overwritten, no additional file generated |