Dynamic Simulation Environment - Network Codec Library

Introduction

Network Codec Library (NCodec) of the Dynamic Simulation Environment (DSE) Core Platform.

NCodec provides C-based codecs and interfaces for exchanging network messages in simulations. It uses a simple stream-based data exchange and can be configured with bus models to create high-fidelity bus simulations. NCodec can be integrated directly from source code or loaded via a shared library.

Codecs: AB Codec (CAN/FlexRay/IP and PDU based networks)
Bus Models: FlexRay
Integrations: DSE ModelC / DSE FMI / DSE Network

Contents

• Usage
  • Code Sample
  • CMake Build Integration
• Codecs
  • AB Codec
• Build
  • Package Layout

Project Structure

dse.ncodec
├── doc/content             # Content for documentation systems
├── dse/ncodec
│   ├── codec/ab            # Automotive Bus (AB) codec implementation
│   │   ├── flexray/        # FlexRay bus model implementation
│   │   └── flexray_pop/    # FlexRay point-of-presence bus model implementation
│   ├── interface
│   │   ├── frame.h         # Frame-based message interface
│   │   └── pdu.h           # PDU-based message interface
│   ├── stream
│   │   └── buffer.h        # Buffer stream implementation
│   ├── codec.c             # NCodec API implementation
│   └── codec.h             # NCodec API headers
├── extra                   # Build infrastructure
├── licenses                # Third-party licenses
└── tests                   # Unit and end-to-end tests

Usage

Code Sample with AB Codec

Note: Full example is available at dse/ncodec/examples/ab-codec

#include <dse/ncodec/codec.h>
#include <dse/ncodec/interface/pdu.h>
#include <dse/ncodec/stream/stream.h>

int cosim_step(NCODEC* nc)
{
    int rc = 0;

    /* Read PDUs from the NCodec. */
    for (;;) {
        NCodecPdu msg = {};
        CHECK_RC(ncodec_read(nc, &msg));
        if (rc == -ENOMSG) break;
        printf("Message is: %s\n", (char*)msg.payload);
    }
    CHECK_RC(ncodec_truncate(nc)); /* Always call _once_ per step. */

    /* Write PDUs to the NCodec. */
    CHECK_RC(ncodec_write(nc, &(struct NCodecPdu){
        .id = 42,
        .payload = (uint8_t*)greeting,
        .payload_len = strlen(greeting),
    }));
    CHECK_RC(ncodec_flush(nc)); /* Call after writing PDUs. */

    return 0;
}

More information about the NCodec API, including a complete example, is available in the Network Codec API Reference. Useful developer documentation relating to the DSE ModelC integration is available in the Developer Documentation.

CMake Build Integration

CMakeLists.txt

include(FetchContent)
FetchContent_Declare(dse_ncodec
    URL           $ENV{DSE_NCODEC_URL}
    SOURCE_SUBDIR dse/ncodec
)
FetchContent_MakeAvailable(dse_ncodec)

add_library(some_lib)
target_include_directories(some_lib
    PRIVATE
        ${dse_ncodec_SOURCE_DIR}
)
target_link_libraries(some_lib
    PUBLIC
        ab-codec
)

Makefile

DSE_NCODEC_REPO ?= https://github.com/boschglobal/dse.ncodec
DSE_NCODEC_VERSION ?= 1.1.0
export DSE_NCODEC_URL ?= $(DSE_NCODEC_REPO)/archive/refs/tags/v$(DSE_NCODEC_VERSION).zip

.PHONY: build
build:
    $(MAKE) build-some_lib

Architecture

Codecs

AB Codec

MIME type: application/x-automotive-bus; interface=stream;

Feature Matrix

	PDU Interface	Frame Interface
Header	interface/pdu.h	interface/frame.h
Stream	stream/buffer.c1	stream/buffer.c1
Schema	pdu.fbs	frame.fbs
Bus Models	supported	-
MIME type	type=pdu; schema=fbs	type=frame; schema=fbs
Language Support	C/C++ Go Python	C/C++
Intergrations	DSE ModelC DSE FMI	DSE ModelC DSE FMI DSE Network
Trace File	enabled by env NCODEC_TRACE_PATH2 NCODEC_TRACE_PATH_<ecu>_<cc>_<swc>_3

Network Support

Bus / Network	PDU Interface	Frame Interface
CAN	✓	✓
FlexRay	✓	-
IP (SomeIP/DoIP)	✓	-
LIN	*4	-
PDU (Autosar Adaptive)	✓	-
Struct (C-Structs)	✓	-

MIME type - Frame Interface

Field	Type	Value (default)	CAN
bus_id	uint8_t	1..	✓✓
node_id	uint8_t	1..	✓✓5
interface_id	uint8_t	0..	✓

Note

✓✓ indicates a required field. Other fields default to 0 or NULL.

MIME type - PDU Interface

Field	Type	Value	CAN	FlexRay	IP	PDU	Struct
ecu_id	uint8_t	06, 1..	✓✓	✓✓	✓✓	✓✓	✓✓
cc_id	uint8_t	0 | 1	-	✓	-	-	-
swc_id	uint8_t	0..	✓7	✓	✓7	✓7	✓7
name	string		✓8	✓8	✓8	✓8	✓8
model	string	flexray	-	✓✓	-	-	-
mode	string	pop	-	✓	-	-	-
pwr	string	on(default)|off|nc	-	✓	-	-	-
vcn	uint8_t	0,1,2	-	✓	-	-	-
poca	uint8_t	1..99	-	✓	-	-	-
pocb	uint8_t	1..99	-	✓	-	-	-
loopback	bool	0(off),1(active)	✓	✓	✓	✓	✓

Note

✓✓ indicates a required field. Other fields default to 0 or NULL.

Build

# Clone the repository.
git clone https://github.com/boschglobal/dse.ncodec.git
cd dse.ncodec

# Optionally set builder images.
export GCC_BUILDER_IMAGE=ghcr.io/boschglobal/dse-gcc-builder:latest

# Build.
make

# Run tests.
make test

# Update source files.
make update

# Generate documentation.
make generate

# Clean build artifacts.
make clean
make cleanall

Package Layout

The AB Codec install target is packaged under the following directory layout:

build/_out/
├── abcodec/
│   ├── lib/
│   │   └── libabcodec.so   # AB Codec shared library
│   └── include/            # AB Codec headers
├── licenses/               # License files
└── doc/                    # Documentation.

Contribute

Please refer to the CONTRIBUTING.md file.

License

Dynamic Simulation Environment Network Codec Library is open-sourced under the Apache-2.0 license.

See the LICENSE and NOTICE files for details.

Third Party Licenses

Third Party Licenses

Footnotes

1. Via FMI 2 String Variables using ASCII85 encoding (ascii85.c). ↩ ↩²

2. Trace files are named ncodec.<name>.bin. If name is not set in the MIME type then <ecu_id>-<cc_id>-<swc_id> is used. ↩

3. When several NCodec objects operate in the same process use a targeted trace envar to enable a specific trace. Use name⁸ to adjust the trace file name. ↩

4. LIN Support is planned. ↩

5. Message filtering on node_id (i.e. filter if Tx Node = Rx Node) is only enabled when this parameter is set. ↩

6. A value of 0 may only be configured for a Point of Presence (PoP) node (i.e. a Gateway model connecting a NCodec network to an external Virtual Bus). ↩

7. Message filtering on swc_id (i.e. filter if Tx Node = Rx Node) is only enabled when this parameter is set. ↩ ↩² ↩³ ↩⁴

8. Name of the NCodec (optional). Used in logging and trace files. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

9. Sets the initial POC State, e.g. 5 = NormalActive (see NCodecPduFlexrayPocState in interface/pdu.h for all POC states). Otherwise POC State is set by the FlexRay model according to its mode of operation. ↩ ↩²