Difference between pages "Technical topic: ASN.1 and ACN - How to add a CRC value to an encoded packet" and "TASTE Step by step tutorial"

From TASTE
(Difference between pages)
Jump to: navigation, search
 
(Hello World)
 
Line 1: Line 1:
== The need ==
+
= Introduction =
  
If you are using ASN.1 to encode the messages you send over a network (as you should!) you may face the situation where ASN.1 cannot know the value of a field before the whole packet is encoded.
+
This tutorial explains how to quickly build a system using [https://taste.tools/ TASTE].
In space-ground links there are two fields of the standard telecommand packets that enter this category:
 
  
* a Length field in the packet header (used to know the number of bytes to wait for on the network interface)
+
Make sure you have either installed the TASTE Virtual machine : https://download.tuxfamily.org/taste/TASTE-VM-10-64bit.ova
* a CRC/Checksum field at the end of the packet
 
  
In the ASN.1 model you may add a placeholder for these fields but the encoder is of course not able to set the value, as it may require to compute it with a user-defined algorithm.
+
...or that you made a manual installation following the instructions here: [[Manual installation on a native platform]]
  
Adding manually the fields to the buffer after the encoding phase is possible but not trivial, as you need to take care of endianness and possibly shift bits here and there. In other words, you loose some benefits of ASN.1 by doing things manually again.
+
If you use the VM, note that the username and password to login are taste / tastevm
  
Luckily ASN1SCC provides help using a simple API to fill a value in the packet after it is encoded. You only need to know where to put the value.
+
= Important =
  
== Solution using ASN.1 and ACN ==
+
Always make sure you are using the latest version of the TASTE tools.
 +
From within the TASTE Virtual machine or your native installation, open a terminal and run the following commands:
  
'''EDIT''' A solution better than the one explained on this page is documented in the ASN.1/ACN user manual. Please check this link and ignore the rest of this page:
+
  $ cd tool-src
 +
  $ ./Update-TASTE.sh
  
http://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_ASN.1_-_An_introduction_to_ACN#Encoding_fields_that_depend_on_the_encoding_binary_stream
+
When it is done, close the current window and open a new terminal.
  
== DEPRECATED PART ==
+
= Hello World =
  
 +
This tutorial explains how to create a basic system to get familiar with the tool.
  
We need two things:
+
== Create a new project ==
  
* to specify the placeholder for the values
+
Run the following command:
* to fill in the value after the packet is encoded
 
  
The placeholder can be present in the ASN.1 type itself, but since it is not a field that is of any relevance to the end user (not application semantics) we will rather use ACN to add it.
+
  $ taste
  
Assuming a top-level structure in ASN.1 that mimicks a space-to-ground telemetry packet (TM):
+
You will be prompted for a project name and a new folder with this name will be created. Always use the '''taste''' command to re-open an existing project.
  
 +
The Space Creator editor will show up:
  
    TM-PACKET ::= '''SEQUENCE''' {
+
:[[File:ClipCapIt-221116-133346.PNG|1000px]]
    header TM-HEADER,
 
    data TM-DATA OPTIONAL
 
    }
 
    with
 
    TM-HEADER ::= '''SEQUENCE''' {
 
    applicationProcessID INTEGER(0..2047),
 
    grouping-flags TC-HEADER-SEQUENCE-FLAGS,
 
    sequence-count INTEGER(0..16383)
 
        }
 
 
  
One of the fields we want to add is at the level of the packet itself: we want to add a packet error control (CRC). Additionally we want to add at the end of the TM-HEADER structure a field that contains the total size of the TM-PACKET record.
+
== Build the system logical architecture ==
  
 +
In the main window, draw a rectangle while pressing the mouse '''right button'''. When you release the mouse button, a contextual menu offers to create a function or a function type:
  
We can create a corresponding ACN encoding structure that "adds" the missing fields (in bold):
+
:[[File:ClipCapIt-221116-133603.PNG]]
  
        TM-PACKET [] {
+
Choose "Function", and rename the box:
                header                [],
 
                data                  [present-when header.data-field-header-flag],
 
                '''packet-error-control    NULL    [pattern '0000000000000000'B, align-to-next byte]'''
 
        }
 
       
 
        TM-HEADER [] {
 
                data-field-header-flag  BOOLEAN        [],
 
                applicationProcessID                    [],
 
                grouping-flags                          [],
 
                sequence-count                          [],
 
                '''packet-length          NULL    [pattern '0000000000000000'B]'''
 
        }
 
  
In your code, you may create the functions that compute the CRC and size after the packet is encoded.
+
:[[File:ClipCapIt-221116-133927.PNG]]
  
Here is the code you can use:
+
Create a second function next to it.
  
      // A buffer to encode your TM
+
Then keep the Ctrl key and the left mouse button clicked to draw a line between the two functions:
      static byte encBuff[TM_PACKET_REQUIRED_BYTES_FOR_ACN_ENCODING];
 
      BitStream bitStrm;
 
      BitStream bitStrm_aux;
 
      flag ret;
 
      int errCode;
 
      int i;
 
      //telemetry packet to be encoded
 
      static TM_PACKET tm_packet = .... 
 
         
 
      // initialize bit stream
 
      BitStream_Init(&bitStrm, encBuff, TM_PACKET_REQUIRED_BYTES_FOR_ACN_ENCODING);
 
         
 
      // Encode value using ACN
 
      ret = TM_PACKET_ACN_Encode(&tm_packet, &bitStrm, &errCode, TRUE);
 
   
 
      '''// First field to add: get the length of the full packet'''
 
      '''asn1SccSint encoded_data_length = BitStream_GetLength(&bitStrm);'''
 
     
 
      '''// Encode length field '''
 
      bitStrm_aux.buf = bitStrm.buf;
 
      bitStrm_aux.count = bitStrm.count;
 
      bitStrm_aux.currentByte = 4;
 
      bitStrm_aux.currentBit = 0;
 
      BitStream_EncodeConstraintWholeNumber(&bitStrm_aux, encoded_data_length - 6, 0, 0xFFFF);
 
     
 
      '''//encode crc field;'''
 
      bitStrm_aux.buf = bitStrm.buf;
 
      bitStrm_aux.count = bitStrm.count;
 
      bitStrm_aux.currentByte = bitStrm.currentByte - 2;
 
      bitStrm_aux.currentBit = 0;
 
      uint16_t crc = gen_crc16(encBuff, bitStrm.currentByte);  // User-defined CRC computation
 
      BitStream_EncodeConstraintWholeNumber(&bitStrm_aux, crc, 0, 0xFFFF);'''
 
     
 
  
That's it!
+
:[[File:ClipCapIt-221116-134009.PNG]]
 +
 
 +
When you release the mouse button, a connection will appear and a dialog will let you name this connection:
 +
 
 +
 
 +
:[[File:ClipCapIt-221116-134200.PNG]]
 +
 
 +
You can select the "kind" of connection this is. It can be an asynchronous message ('''sporadic''') or a simple, immediate function call (e.g. '''unprotected''').
 +
 
 +
Add a connection in the other direction by using Ctrl+Left Click from the function on the right and releasing the keys when hovering on the left function. If you name it "Hi", it will look like this:
 +
 
 +
:[[File:ClipCapIt-221116-134541.PNG]]
 +
 
 +
Last, we will add a cyclic interface to the "caller" function. To do this, right click on the Caller function and choose the "Provided Interface" option from the menu entry:
 +
 
 +
:[[File:ClipCapIt-221116-134816.PNG]]
 +
 
 +
In the dialog, name it ("trigger", choose "Periodic" for the kind attribute, and leave the period to 1000 ms:
 +
 
 +
:[[File:ClipCapIt-221116-134925.PNG]]
 +
 
 +
== Create data types ==
 +
 
 +
TASTE software works with data, and relies on well defined data structures. They are captured with the ASN.1 language.
 +
 
 +
On the Workspace area of the editor you will see a file with the ".asn" extension. The file name itself is the name of your project. Double click on this file to open the editor. The default file contains a lot of built-in documentation to help you with the syntax of the language.
 +
 
 +
For this example we will create a type to store a simple counter with a range of values from 0 to 3:
 +
 
 +
:[[File:ClipCapIt-221116-135538.PNG]]
 +
 
 +
After this is done, go back to the main diagram by selecting the file named "interfaceview.xml". Note that you may also split the window in the IDE to view both files at the same time.
 +
 
 +
== Select the implementation language of each function ==
 +
 
 +
To create an implementation of the system, we have to select a language for each function (caller and callee). We will use C for the callee and SDL for the caller.
 +
To do this, double click on each function, and select the tab named "Implementations". Change the language accordingly (the default being SDL, there is no need to touch the caller function):
 +
 
 +
:[[File:ClipCapIt-221116-135952.PNG]]
 +
 
 +
 
 +
== Implement the functions ==
 +
 
 +
We start with the "callee" function. Right click on the function and select "Edit Implementation" from the contextual menu.
 +
After being prompted to save the model (do it), wait a few seconds to enter the C editor in the IDE:
 +
 
 +
:[[File:ClipCapIt-221116-140250.PNG]]
 +
 
 +
Edit the code at will. The IDE provides auto-completion and on-the-fly syntax and semantic checks:
 +
 
 +
:[[File:ClipCapIt-221116-140500.PNG]]
 +
 
 +
When you are done, go back to the main diagram editor (double click on "interfaceview.xml" in the workspace on the left).
 +
 
 +
Right-click on Caller and choose "Edit Implementation". This will open the SDL editor (OpenGEODE).
 +
 
 +
:[[File:ClipCapIt-221116-140708.PNG]]
 +
 
 +
If you are not familiar with SDL, a complete documentation is built-in the tool (on the right).
 +
Double click on the Caller block to enter the state machine editor.
 +
 
 +
You can create the state machine using the set of symbols on the left of the editor. In this example, when the periodic trigger is received, the "Hello" message will be sent (to the callee function), and then the "Hi" message will be expected in return. After a few cycles, we enter a state named "Enough" and stop repeating this polite exchange.
 +
 
 +
:[[File:ClipCapIt-221116-142433.PNG]]
 +
 
 +
You may want to visualize this simple state machine with a "statechart" representation. Click on the corresponding tab on top of the editor:
 +
 
 +
:[[File:ClipCapIt-221116-141927.PNG]]
 +
 
 +
You may now save the model and quit OpenGEODE, to get back to the main interface view.
 +
 
 +
== Quick build and run ==
 +
 
 +
At this stage you can already build the system. Click on the "Play" button on the bottom left corner of the tool:
 +
 
 +
:[[File:ClipCapIt-221116-142131.PNG]]
 +
 
 +
 
 +
After a few seconds of build, you will see the system run in a console:
 +
 
 +
:[[File:ClipCapIt-221116-142547.PNG]]
 +
 
 +
When you do Ctrl-C to stop the application you can visualize a log of the execution in a file that was generated and that appeared in the workspace:
 +
 
 +
:[[File:ClipCapIt-221116-142758.PNG]]
 +
 
 +
== Create a deployment to run on target ==
 +
 
 +
This quick build produced a Linux binary. But you may want to build on a different platform, for example a Leon processor with the RTEMS6 Qualified RTOS.
 +
 
 +
To do this you need to model the deployment of your system. On the workspace, right-click on "Other files" and choose "Add new"
 +
 
 +
:[[File:ClipCapIt-221116-143200.PNG]]
 +
 
 +
In the dialog select "Deployment View file":
 +
 
 +
:[[File:ClipCapIt-221116-143234.PNG]]
 +
 
 +
 
 +
Then on the next screen you may rename it, but keep the ".dv.xml" file extension:
 +
 
 +
:[[File:ClipCapIt-221116-143320.PNG]]
 +
 
 +
This will open a new editor, from which you can drag and drop deployment boards. Select for example this one:
 +
 
 +
:[[File:ClipCapIt-221116-143650.PNG]]
 +
 
 +
When you right click on the board, you can bind the functions (caller and callee) to it.
 +
 
 +
Save the project, and click again on the "Run" button. This time the binary will be created using the RTEMS Cross compiler for the GR740 board that you selected, and it will execute using a SPARC/Leon built-in emulator. The output should be the same as before:
 +
 
 +
:[[File:ClipCapIt-221116-143903.PNG]]
 +
 
 +
 
 +
... except for the timings, as the Leon emulator does not reproduce the waiting periods correctly (the 1 second beween each trigger isn't right). If you download this binary on a real board however it should work as expected.

Revision as of 13:40, 16 November 2022

Introduction

This tutorial explains how to quickly build a system using TASTE.

Make sure you have either installed the TASTE Virtual machine : https://download.tuxfamily.org/taste/TASTE-VM-10-64bit.ova

...or that you made a manual installation following the instructions here: Manual installation on a native platform

If you use the VM, note that the username and password to login are taste / tastevm

Important

Always make sure you are using the latest version of the TASTE tools. From within the TASTE Virtual machine or your native installation, open a terminal and run the following commands:

  $ cd tool-src
  $ ./Update-TASTE.sh

When it is done, close the current window and open a new terminal.

Hello World

This tutorial explains how to create a basic system to get familiar with the tool.

Create a new project

Run the following command:

  $ taste

You will be prompted for a project name and a new folder with this name will be created. Always use the taste command to re-open an existing project.

The Space Creator editor will show up:

ClipCapIt-221116-133346.PNG

Build the system logical architecture

In the main window, draw a rectangle while pressing the mouse right button. When you release the mouse button, a contextual menu offers to create a function or a function type:

ClipCapIt-221116-133603.PNG

Choose "Function", and rename the box:

ClipCapIt-221116-133927.PNG

Create a second function next to it.

Then keep the Ctrl key and the left mouse button clicked to draw a line between the two functions:

ClipCapIt-221116-134009.PNG

When you release the mouse button, a connection will appear and a dialog will let you name this connection:


ClipCapIt-221116-134200.PNG

You can select the "kind" of connection this is. It can be an asynchronous message (sporadic) or a simple, immediate function call (e.g. unprotected).

Add a connection in the other direction by using Ctrl+Left Click from the function on the right and releasing the keys when hovering on the left function. If you name it "Hi", it will look like this:

ClipCapIt-221116-134541.PNG

Last, we will add a cyclic interface to the "caller" function. To do this, right click on the Caller function and choose the "Provided Interface" option from the menu entry:

ClipCapIt-221116-134816.PNG

In the dialog, name it ("trigger", choose "Periodic" for the kind attribute, and leave the period to 1000 ms:

ClipCapIt-221116-134925.PNG

Create data types

TASTE software works with data, and relies on well defined data structures. They are captured with the ASN.1 language.

On the Workspace area of the editor you will see a file with the ".asn" extension. The file name itself is the name of your project. Double click on this file to open the editor. The default file contains a lot of built-in documentation to help you with the syntax of the language.

For this example we will create a type to store a simple counter with a range of values from 0 to 3:

ClipCapIt-221116-135538.PNG

After this is done, go back to the main diagram by selecting the file named "interfaceview.xml". Note that you may also split the window in the IDE to view both files at the same time.

Select the implementation language of each function

To create an implementation of the system, we have to select a language for each function (caller and callee). We will use C for the callee and SDL for the caller. To do this, double click on each function, and select the tab named "Implementations". Change the language accordingly (the default being SDL, there is no need to touch the caller function):

ClipCapIt-221116-135952.PNG


Implement the functions

We start with the "callee" function. Right click on the function and select "Edit Implementation" from the contextual menu. After being prompted to save the model (do it), wait a few seconds to enter the C editor in the IDE:

ClipCapIt-221116-140250.PNG

Edit the code at will. The IDE provides auto-completion and on-the-fly syntax and semantic checks:

ClipCapIt-221116-140500.PNG

When you are done, go back to the main diagram editor (double click on "interfaceview.xml" in the workspace on the left).

Right-click on Caller and choose "Edit Implementation". This will open the SDL editor (OpenGEODE).

ClipCapIt-221116-140708.PNG

If you are not familiar with SDL, a complete documentation is built-in the tool (on the right). Double click on the Caller block to enter the state machine editor.

You can create the state machine using the set of symbols on the left of the editor. In this example, when the periodic trigger is received, the "Hello" message will be sent (to the callee function), and then the "Hi" message will be expected in return. After a few cycles, we enter a state named "Enough" and stop repeating this polite exchange.

ClipCapIt-221116-142433.PNG

You may want to visualize this simple state machine with a "statechart" representation. Click on the corresponding tab on top of the editor:

ClipCapIt-221116-141927.PNG

You may now save the model and quit OpenGEODE, to get back to the main interface view.

Quick build and run

At this stage you can already build the system. Click on the "Play" button on the bottom left corner of the tool:

ClipCapIt-221116-142131.PNG


After a few seconds of build, you will see the system run in a console:

ClipCapIt-221116-142547.PNG

When you do Ctrl-C to stop the application you can visualize a log of the execution in a file that was generated and that appeared in the workspace:

ClipCapIt-221116-142758.PNG

Create a deployment to run on target

This quick build produced a Linux binary. But you may want to build on a different platform, for example a Leon processor with the RTEMS6 Qualified RTOS.

To do this you need to model the deployment of your system. On the workspace, right-click on "Other files" and choose "Add new"

ClipCapIt-221116-143200.PNG

In the dialog select "Deployment View file":

ClipCapIt-221116-143234.PNG


Then on the next screen you may rename it, but keep the ".dv.xml" file extension:

ClipCapIt-221116-143320.PNG

This will open a new editor, from which you can drag and drop deployment boards. Select for example this one:

ClipCapIt-221116-143650.PNG

When you right click on the board, you can bind the functions (caller and callee) to it.

Save the project, and click again on the "Run" button. This time the binary will be created using the RTEMS Cross compiler for the GR740 board that you selected, and it will execute using a SPARC/Leon built-in emulator. The output should be the same as before:

ClipCapIt-221116-143903.PNG


... except for the timings, as the Leon emulator does not reproduce the waiting periods correctly (the 1 second beween each trigger isn't right). If you download this binary on a real board however it should work as expected.