Hello World 2
1. Introduction
In the previous tutorial, you worked with the MessagePrinter Component Type,
and learned how to configure it to print a message you chose at build time.
This helped you understand the various stages involved in building ground
software with Groundkit, but was not a very realistic development task.
Typically, when using Groundkit to produce your ground software you will need to create or modify Component Types and write their implementations.
In this tutorial you will learn how to do that. You will add new functionality
to the MessagePrinter Component Type, implement it, and then test it in a
Deployment Type.
Along the way, you will learn how to create Actions which take Arguments. You will also be introduced to Parameters, which are used to give access to, and control over, a Component Instance's State.
|
In this tutorial, you will:
|
2. Before You Begin
Guidance on the styles and conventions used in these tutorials is available here.
Unless otherwise directed, all commands in this tutorial must be run in the the_basics/HelloWorld2 workspace.
You must have Groundkit installed as described in the Getting Started Guide.
Install a copy of the tutorials locally by running hgk-prepare-tutorials.
Navigate to the the_basics/HelloWorld2 workspace in a terminal and run hgk workspace prepare to ensure it is ready to use.
3. Actions With Arguments
In the previous tutorial, you were briefly introduced to Actions as a way to execute a Component Instance's functionality on command.
Actions can also have an Argument. Like the arguments of a method in Java, an Action's Argument can be used to dynamically control its behaviour.
|
In this section of the tutorial you will add a new |
3.1. Adding the printUserMessage Action
To add a new Action to a Component Type, you need to add a new <Action>
element to its componentType.xml. To specify that an Action takes an
Argument, you also need to include an <Argument> element.
Open the MessagePrinter componentType.xml, found here:
library/componenttypes/messageprinter/src/main/resources/com/brightascension/componenttypes/messageprinter/componentType.xml
Add the following <Action> element below the printGreeting Action:
<Action name="printUserMessage">
<Description>
Print a message, provided as an argument, to the console.
</Description>
<Argument name="message">
<Description>
The message to print.
</Description>
<Type>
<Blob fixed="false" maxLength="127"/>
</Type>
</Argument>
</Action>
Having changed the componentType.xml, you now need to generate the
Component Type.
hgk component-type generate MessagePrinter
Since an implementation file already exists for the MessagePrinter
Component Type, the above command creates a template file. This
file contains skeleton code for the Component Type's updated implementation
and can be used to update the original file. The template file is named
MessagePrinterImpl.java.template and can be found here:
library/componenttypes/messageprinter/src/main/java/com/brightascension/componentimpls/messageprinter/messageprinterimpl/MessagePrinterImpl.java.template
To update the original implementation file, you can simply copy over the new methods that are needed from the generated template file. It is recommended that you retain the same method order in the original file as is in the template file to help with comparisons and maintenance.
Copy the skeleton code for MessagePrinterImpl.printUserMessage(byte[] message) from
MessagePrinter.java.template (including its description banner) and paste it
below the MessagePrinterImpl.printGreeting() method in MessagePrinterImpl.java.
Notice that, unlike the MessagePrinter_printGreeting() method, the new
Action function has a byte[] message argument. The maximum length of this byte array is enforced by some generated template code against limits derived from the model. These limits can be found in library/componenttypes/messageprinter/src/main/java/com/brightascension/componentimpls/messageprinter/messageprinterimpl/include/container/component/aas/MessagePrinterImplActions.java with the length checking implemented in library/componenttypes/messageprinter/generated/main/java/com/brightascension/componentimpls/messageprinter/messageprinterimpl/component/aas/MessagePrinterImplActionSource.java.
In this case, the generated code is validating that message.length does not exceed
the maximum length of the message Argument specified in the XML excerpt you
just added.
|
Many different methods and static fields are generated from the data entered into the model for a Component Type. We demonstrate some of these static fields in these tutorials. In future we are planning to provide more complete documentation of all the generated methods and static fields which your Component Types can use. |
You must now update the implementation so it prints out the byte array message.
You can try this yourself if you wish, or if you’d prefer you can use the implementation we’ve provided below.
Show the modifications to the MessagePrinterImpl.printUserMessage() Action skeleton
import com.brightascension.componentimpls.messageprinter.messageprinterimpl.include.container.MessagePrinterImplContainer;
import com.brightascension.componentimpls.messageprinter.messageprinterimpl.include.container.MessagePrinterImplInterface;
import com.brightascension.genone.exception.GenOneBaseException;
+import com.brightascension.genone.util.SerialisationUtils;
/**
* This is the Component Implementation for MessagePrinter.
@@ -65,6 +66,18 @@ public class MessagePrinterImpl implements MessagePrinterImplInterface {
container.logInfo("Greeting says '{}'", greeting);
}
+ /**
+ * The printUserMessage action from the Component Type : MessagePrinter
+ * Print a message, provided as an argument, to the console.
+ * @param message The message to print.
+ * @throws GenOneBaseException
+ */
+ public void printUserMessage(byte[] message) throws GenOneBaseException {
+ String messageStr = SerialisationUtils.deserialiseFixedString(message);
+ container.logInfo("Printing message '{}'", messageStr);
+ }
+
@Override
public String toString() {
return String.format("%s - %d", instanceName, id);
The MessagePrinter Component Type now has a new Action printUserMessage.
3.2. Testing the printUserMessage Action
Like in the HelloWorld1 tutorial, MessagePrinter has already been
instantiated for you in a Deployment Type, and that Deployment Type has
been instantiated in a Mission.
In order to invoke the printUserMessage Action, you must build the
HelloWorld2 Mission, and run the MessagePrinterDemo Deployment Instance.
Use the same commands as in the previous tutorial to build the Mission and run the Deployment Instance:
hgk mission build HelloWorld2
java -jar output/missions/HelloWorld2//MessagePrinterDemo/MessagePrinterDemo/MessagePrinterDemo.jar
The Deployment Instance should start successfully:
15:50:13.547 [main] INFO c.b.m.h.m.m.deployment.Deployment - Initialising the MessagePrinterDeployment Deployment.
15:50:13.602 [GRPCServerInst-serverStartup-thread-0] INFO c.b.c.g.g.g.GRPCServerImpl - Starting server on port: 8999
With the Deployment Instance running, you can now interact with it via gRPC.
Use the same approach as in the previous tutorial to open Bruno and load the collection provided at bruno/HelloWorld2:
-
Launch Bruno from the application menu.
-
Click the Open Collection button and navigate to the collection and click the Open button.
-
Select the
invoke_action_print_user_datarequest under theHelloWorld2collection.
{
"provider_id": {
"target_id": 0,
"deployment_id": 0,
"local_provider_id": 0
},
"channel_id": 0,
"selection_id": 1,
"args_in": "SGVsbG9Xb3JsZDI="
}
Notice that the selection_id is set to 1 in contrast to the invoke_action_print_greeting request. This is because the actions are indexed in the order they are defined in the componentType.xml file.
The request JSON contains an args_in JSON property for entering the printUserGreeting Argument. You can use this property to specify the message you want the Component Instance
to print to the terminal, when this Action is invoked. The value should be encoded in base64.
Replace the args_in value with the string that you want to be printed to the terminal, in base64 encoding.
The Linux command line base64 utility can be used to do this encoding.
printf "Your string here" | base64
Show example argument
To print the word HelloWorld2, update args_in with its base64 equivalent which is
SGVsbG9Xb3JsZDI=.
Click the → right arrow button at the top of the request to invoke the Action.
If successful, the terminal running your MessagePrinterDemo Deployment Instance should
now display your message:
16:16:25.919 [grpc-default-executor-5] INFO c.b.c.m.m.MessagePrinterImpl - Printing message 'HelloWorld2'
Once you are happy the Action is working, terminate the process using the same approach as in the previous tutorial.
Keep Bruno open so you can use it again later in the tutorial.
|
In this section you added an Action which takes an
Argument - In the next section you will be introduced to Parameters. You will
create one which interacts with the |
4. Parameters
Parameters are one of the most widely used features of Component Types created with Groundkit. Almost every Component Type has at least one Parameter to give insight into, or control over, its behaviour:
-
Many Component Types have an
enabledParameter to allow them to be switched on and off. -
Component Types which handle data transmission and reception may have Parameters for counting the number of bytes transmitted and received.
-
A Component Type for handling CFDP transmission might use Parameters to control the keep alive interval, and other settings.
Like variables in typed programming languages, Parameters have types. Parameters may be integers, floats, bitfields (not currently supported), raw byte blobs. They may also be lists of integers, floats or raw byte blobs.
Parameters are either mutable or read-only. The value of Mutable Parameters can be set externally to the Component Type, whereas the value of Read-Only Parameters can only be set internally by the Component Implementation.
|
In this section of the tutorial, you will add a Read-Only Parameter indicating
how many times the This will require the addition of a new Parameter to the Component Type, the
addition of a new State variable to the Component Type Structure, and
modification of the |
4.1. Adding the actionCounter Parameter
To add a new Parameter to a Component Type, you need to add a new
<Parameter> element to its componentType.xml. MessagePrinter currently
has no Parameters, so a <Parameters> element is also required.
Open the MessagePrinter componentType.xml and add the following
<Parameters> element just below the <!-- Parameters --> comment:
<Parameters>
<Parameter name="actionCounter" readOnly="true">
<Description>
The number of times the action has been invoked.
</Description>
<Type>
<Integer signed="false" bits="32"/>
</Type>
</Parameter>
</Parameters>
As before, this changes the Component Type, so you must generate
MessagePrinter:
hgk component-type generate MessagePrinter
The above command overwrites the template file MessagePrinterImpl.java.template with
updated code including a new Parameter getter function,
MessagePrinter.getActionCounter().
Copy this function, including its description banner, and paste it in
MessagePrinterImpl.java just below the MessagePrinterImpl.printUserMessage()
function.
You will now update the MessagePrinterImpl to record the number of times MessagePrinterImpl.printUserMessage() has been accessed, and implement the getter function.
4.2. Adding State to MessagePrinter
You need each instance of MessagePrinter to have its own counter, so a new field is required.
|
It is good practice to ensure the new member’s name and type match those
defined for the Parameter in the |
Open MessagePrinterImpl.java and add a new AtomicLong actionCounter field.
Show the added MessagePrinterImpl field
@@ -7,6 +7,9 @@ package com.brightascension.componentimpls.messageprinter.messageprinterimpl;
import com.brightascension.componentimpls.messageprinter.messageprinterimpl.include.container.MessagePrinterImplContainer;
import com.brightascension.componentimpls.messageprinter.messageprinterimpl.include.container.MessagePrinterImplInterface;
import com.brightascension.genone.exception.GenOneBaseException;
import java.nio.charset.StandardCharsets;
+import java.util.concurrent.atomic.AtomicLong;
/**
* This is the Component Implementation for MessagePrinter.
@@ -24,6 +27,8 @@ public class MessagePrinterImpl implements MessagePrinterImplInterface {
// Container reference
private final MessagePrinterImplContainer container;
+ private AtomicLong actionCounter = new AtomicLong();
+
/**
* Constructor for MessagePrinter
*
4.3. Thread safety
Note that you need to access MessagePrinterImpl.actionCounter in 2 separate contexts:
-
MessagePrinterImpl.getActionCounter()to return its value to the user. -
MessagePrinterImpl.printUserMessage()to increment it.
In general, there is nothing to stop the actionCounter Parameter and
printUserMessage Action from being accessed concurrently. For example, the
Action could be scheduled for autonomous invocation at the same time as a user
happens to request the Parameter's value.
To prevent potentially dangerous race conditions, Component Implementations
must use Locks to protect resources which may be accessed from
different contexts. In most cases, we recommend using java.util.concurrent.atomic.* types. In this case, we have used an AtomicLong.
|
Practically, the chance of race conditions in this case is extremely small, but not negligible! While the protected resource in this tutorial is very simple (a single 32-bit word), there are many situations, like the handling of packets in communications Component Types, where a failure to correctly protect underlying resources can cause very difficult to diagnose issues when the software is integrated. |
4.4. Implementing the actionCounter Parameter
You now have all the elements needed to update the implementation such that
actionCounter behaves as specified in the componentType.xml:
-
An underlying atomic State variable held in the
MessagePrinterImpl.actionCounterfield.
You will now update the implementation using these elements.
First, modify the MessagePrinterImpl.getActionCounter() Parameter getter
function you added earlier so it returns the current value of MessagePrinterImpl.actionCounter to
the user, accessing it from within the AtomicLong.
Show the updated MessagePrinterImpl.getActionCounter() implementation
@@ -88,8 +91,7 @@ public class MessagePrinterImpl implements MessagePrinterImplInterface {
*/
@Override
public long getActionCounter() throws GenOneBaseException {
- // TODO: Implement actionCounter get accessor
- throw new OperationNotProvidedException();
+ return actionCounter.get();
}
@Override
Next, update the MessagePrinterImpl.printUserMessage() method so that,
each time the Action is invoked, it increments the actionCounter State
variable.
Show the change required in the MessagePrinterImpl.printUserMessage() implementation
@@ -73,6 +76,7 @@ public class MessagePrinterImpl implements MessagePrinterImplInterface {
* @throws GenOneBaseException
*/
public void printUserMessage(byte[] message) throws GenOneBaseException {
+ actionCounter.incrementAndGet();
String messageStr = SerialisationUtils.deserialiseFixedString(message);
container.logInfo("Printing message '{}'", messageStr);
4.5. Testing the actionCounter Parameter
You have now completed the MessagePrinter implementation.
In order to test the behaviour of actionCounter you must once again
build the HelloWorld2 Mission and run the MessagePrinterDemo
Deployment Instance.
hgk mission build HelloWorld2
java -jar output/missions/HelloWorld2//MessagePrinterDemo/MessagePrinterDemo/MessagePrinterDemo.jar
Return to your active Bruno window.
Select the get_parameter request, and click the refresh proto file methods button. Notice that we use a selection_id of 0 to target the first (and only) Parameter in the Component.
Send a request to get the value of the actionCounter Parameter by clicking the send request button. You should get the following response:
{
"time": {
"basic": 0,
"fractional": 0
},
"value": "AAAAAA=="
}
Here the value parameter is the value of the 32-bit integer actionCounter Parameter, base64 encoded. You can decode it on the Linux command line with base64 and xxd:
> echo -n 'AAAAAA==' | base64 -d | xxd
00000000: 0000 0000 ....
As you can see, a value of 0 is returned for the Parameter, as expected as this is the Parameter's initial value.
Invoke the printUserMessage Action by selecting and sending the invoke_action_print_user_message request.
Issue another get command on the actionCounter Parameter.
The returned value should have incremented by one since the last time it was
issued as the printUserMessage Action has been invoked once since then.
5. Wrap Up
In this tutorial you have:
-
Added to a Component Type's implementation using the same steps that will be required when working on your own Component Types in the future.
-
Extended your understanding of Actions to include Arguments, and learned how they can be used to provide input to your Component Types.
-
Learned about Parameters and how they can be implemented using your Component Type Structure.
In the next tutorial you will be introduced to more capabilities you can add to Component Types. This will build on the understanding you have developed here using a different Component Type and Deployment Type.
Click here to move on to that now.