Difference between pages "Technical topic: ASN.1 and ACN - How to add a CRC value to an encoded packet" and "TASTE Communication Device"

From TASTE
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
== The need ==
+
== Introduction ==
 +
CommunicationDevice (CD) is a new type of TASTE project, that allows to model low level system drivers and integrate CD driver with existing or new TASTE project. It comes with two pre-defined templates: Broker and Broker + Packetizer. Depending on a selected template CD allows to model either Broker or Broker and Packetizer communication components. CommunicationDevice is a part of the SpaceCreator and Kazoo projects.
  
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.
+
== Capabilities ==
In space-ground links there are two fields of the standard telecommand packets that enter this category:
+
The following functionalities are supported:
 +
* creation of new CD project from QTC wizard – SpaceCreator
 +
* modeling and implementation of broker and packetizer
 +
* CD code generation done be Kazoo templates
 +
* integration with full TASTE project
  
* a Length field in the packet header (used to know the number of bytes to wait for on the network interface)
+
==How to create CD project==
* a CRC/Checksum field at the end of the packet
+
Communication device project can be created form QT Creator wizard that can be opened with TASTE command. Then under File->New File or Project (Ctrl + N)
 +
[[File:Cd_wizard_2.png]]
  
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.
 
  
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.
+
Non-Qt Project -> Communication Device Project
  
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.
+
[[File:Cd wizard 1.png]]
  
== Solution using ASN.1 and ACN ==
 
  
'''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 wizard starts with “Project Location” tab. User shall provide Name for the project and path under which project will be created.
  
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
+
[[File:Cd_wizard_3.png]]
  
== DEPRECATED PART ==
+
Next tab “Project Initialization” provides capabilities of selecting interface view template and CD board. Under IV template either “Broker” or “Broker_Packetizer” can be selected. Under Communication Device board either “x86 Linux CPP” or “SAM V71 FreeRTOS N7S” can be selected.
  
 +
[[File:Cd_wizard_4.png]]
  
We need two things:
+
Next tab is standard “Kit Selection” tab.
  
* to specify the placeholder for the values
+
[[File:Cd_wizard_5.png]]
* 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.
+
Under last tab that is “Project Management” version control can be added. Also wizard displays all files that will be added to Communication Device project.
  
Assuming a top-level structure in ASN.1 that mimicks a space-to-ground telemetry packet (TM):
+
[[File:Cd_wizard_6.png]]
  
 +
===Generated CD project files details===
 +
Communication Device Project wizard adds the following files to the project:
 +
{| class="wikitable"
 +
|-
 +
| --acn-filepath-prefix <prefix>
 +
| <prefix> to add at the beginning of the ACN output filepath
 +
|-
 +
| --asn1-filepath-prefix <prefix>
 +
| <prefix> to add at the beginning of the ASN.1 output filepath
 +
|}
  
    TM-PACKET ::= '''SEQUENCE''' {
+
{| class="wikitable"
    header TM-HEADER,
+
|-
    data TM-DATA OPTIONAL
+
|--taste.pro – empty taste.pro file that will be automatically generated during build
    }
+
|-
    with
+
|-- Makefile – entry build and clean procedure that includes Kazoo and SC dependencies definitions
    TM-HEADER ::= '''SEQUENCE''' {
+
|-
    applicationProcessID INTEGER(0..2047),
+
|-- deploymentvew.dv.xml – predefined deploymentview.dv.xml that includes CD build partition
    grouping-flags TC-HEADER-SEQUENCE-FLAGS,
+
|-
    sequence-count INTEGER(0..16383)
+
|*--interfaceview.xml – interfaceview with Broker, Packetizer and interfaces. In this file user shall model Broker or Broker and Packetizer (depending on a template) along with required and provided components interfaces.
        }
+
|-
+
|-- <project name>.acn – ACN project model for custom binary encoding rules.
 +
|-
 +
|-- <project name>.asn – ASN non user-editable model that contains all the basic data types.
 +
|-
 +
|-- <project name>.pro/shared – QTC project files with custom user build settings.
 +
|-
 +
|-- <project name>configuration.acn - ACN project configuration model for custom binary encoding rules.
 +
|-
 +
|-- <project name>configuration.asn - ASN user-editable model that contains definition of Driver Configuration. This file will be used by ocarina-components.aadl and Board1.xml and shall be implemented by the user.
 +
|-
 +
|--<project name>privatedata.acn - ACN project privatedata model for custom binary encoding rules.
 +
|-
 +
|-- <project name>privatedata.asn - ASN user-editable model that contains definition of Private Data structure. This type shall be used in main.c[pp] to indicate the type of the variable that is passed as a private pointer to the driver. Shall be implemented by the user.
 +
|}
  
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.
+
==Exemplary CD broker and packetizer modeling and implementation==
 +
Based on selected CD “Interface view template” either broker or broker and packetizer can be modeled and implemented. In this example second template will be used.  
  
 +
===CD IV file specifics – fixed system elements===
 +
After opening IV file in the editor user can find (depending on selected template) Broker and Packetizer components. These are virtual components that are not taken for final code generation. Purpose of those elements is to provide “must have” set of interfaces. Those are required to match newly created and modeled communication components to existing in TASTE runtime calls.
  
We can create a corresponding ACN encoding structure that "adds" the missing fields (in bold):
+
[[File:Cd_broker_pack_iv_1.png|1100px]]
  
        TM-PACKET [] {
+
User can’t remove those element neither the interfaces and will be informed about that while trying to do so.
                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:Cd_broker_pack_iv_2.png]]
  
Here is the code you can use:
+
===Modeling Packetizer component===
 +
While modeling Packetizer user shall provide a TASTE function that implements needed interfaces and connect that function to pre-defined virtual Packetizer component. Also each interface shall contain set of input and output parameters. The easiest way to do so is by dragging each interface from virtual Packetizer with left Ctrl key pressed and drop it on custom function. This way each interface will be copied along with set of parameters.
  
      // A buffer to encode your TM
+
[[File:Cd_broker_pack_iv_3.png|1100px]]
      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:Cd_pack_params_1.png|t300px]]
 +
[[File:Cd_pack_params_2.png|500px]]
 +
 
 +
To avoid build errors another function can be connected to Broker and it’s implementation is not required.
 +
 
 +
===Implementation of Packetizer component===
 +
At this point CD project is able to generate source code for MyPacketizer function that can be extended with user implementation. Screens below presents empty mypacketizer.c/h files.
 +
 
 +
 
 +
[[File:Cd_mypack_code_2.png|t300px]]
 +
[[File:Cd_mypack_code_1.png|400px]]
 +
 
 +
For this example simple implementations of “Packetize” and “Depacketize” functions will be implemented and Init function will not be used. Screens bellow presents exemplary implementation of those functions.
 +
 
 +
 
 +
[[File:Cd_mypack_code_6.png|t300px]]
 +
[[File:Cd_mypack_code_5.png|400px]]
 +
 
 +
Communication Device project with packetizer component implementation is ready to be integrated wit full TASTE project. See another chapters to follow TASTE project integration.

Revision as of 17:47, 29 November 2022

Introduction

CommunicationDevice (CD) is a new type of TASTE project, that allows to model low level system drivers and integrate CD driver with existing or new TASTE project. It comes with two pre-defined templates: Broker and Broker + Packetizer. Depending on a selected template CD allows to model either Broker or Broker and Packetizer communication components. CommunicationDevice is a part of the SpaceCreator and Kazoo projects.

Capabilities

The following functionalities are supported:

  • creation of new CD project from QTC wizard – SpaceCreator
  • modeling and implementation of broker and packetizer
  • CD code generation done be Kazoo templates
  • integration with full TASTE project

How to create CD project

Communication device project can be created form QT Creator wizard that can be opened with TASTE command. Then under File->New File or Project (Ctrl + N) Cd wizard 2.png


Non-Qt Project -> Communication Device Project

Cd wizard 1.png


CD wizard starts with “Project Location” tab. User shall provide Name for the project and path under which project will be created.

Cd wizard 3.png

Next tab “Project Initialization” provides capabilities of selecting interface view template and CD board. Under IV template either “Broker” or “Broker_Packetizer” can be selected. Under Communication Device board either “x86 Linux CPP” or “SAM V71 FreeRTOS N7S” can be selected.

Cd wizard 4.png

Next tab is standard “Kit Selection” tab.

Cd wizard 5.png

Under last tab that is “Project Management” version control can be added. Also wizard displays all files that will be added to Communication Device project.

Cd wizard 6.png

Generated CD project files details

Communication Device Project wizard adds the following files to the project:

--acn-filepath-prefix <prefix> <prefix> to add at the beginning of the ACN output filepath
--asn1-filepath-prefix <prefix> <prefix> to add at the beginning of the ASN.1 output filepath
*--interfaceview.xml – interfaceview with Broker, Packetizer and interfaces. In this file user shall model Broker or Broker and Packetizer (depending on a template) along with required and provided components interfaces.

Exemplary CD broker and packetizer modeling and implementation

Based on selected CD “Interface view template” either broker or broker and packetizer can be modeled and implemented. In this example second template will be used.

CD IV file specifics – fixed system elements

After opening IV file in the editor user can find (depending on selected template) Broker and Packetizer components. These are virtual components that are not taken for final code generation. Purpose of those elements is to provide “must have” set of interfaces. Those are required to match newly created and modeled communication components to existing in TASTE runtime calls.

Cd broker pack iv 1.png

User can’t remove those element neither the interfaces and will be informed about that while trying to do so.

Cd broker pack iv 2.png

Modeling Packetizer component

While modeling Packetizer user shall provide a TASTE function that implements needed interfaces and connect that function to pre-defined virtual Packetizer component. Also each interface shall contain set of input and output parameters. The easiest way to do so is by dragging each interface from virtual Packetizer with left Ctrl key pressed and drop it on custom function. This way each interface will be copied along with set of parameters.

Cd broker pack iv 3.png


t300px Cd pack params 2.png

To avoid build errors another function can be connected to Broker and it’s implementation is not required.

Implementation of Packetizer component

At this point CD project is able to generate source code for MyPacketizer function that can be extended with user implementation. Screens below presents empty mypacketizer.c/h files.


t300px Cd mypack code 1.png

For this example simple implementations of “Packetize” and “Depacketize” functions will be implemented and Init function will not be used. Screens bellow presents exemplary implementation of those functions.


t300px Cd mypack code 5.png

Communication Device project with packetizer component implementation is ready to be integrated wit full TASTE project. See another chapters to follow TASTE project integration.