Skip to content

open62541 command reference

ncc c generates a function that adds your model's nodes to an open62541 server. cncc accepts the same arguments.

ncc c <input> [<input> ...] -o <dir> [--shortname <name>] [options]
Flag Meaning
<input> Target XMLs to combine. Multiple targets require --shortname.
-e, --existing <path> A NodeSet the model depends on. Repeatable. Accepts SHORTNAME=PATH, but the shortname is discarded. o6\Python uses a separate dependency grammar.
--shortname <name> Explicit C output basename and initializer; must start with an ASCII letter and contain only ASCII letters, digits and underscores. C keywords are rejected.
-o, --output <dir> Output directory. Required; created if missing.
-b, --blacklist <file> Remove listed nodes and their references. One NodeId per line; repeatable.
-i, --ignore <file> Keep listed nodes for resolution but omit their generated code. One NodeId per line; repeatable.
-t, --types-array <name> Custom types array to bind against, e.g. UA_TYPES_DI. Repeatable; also emits the matching include — see Datatype tables.
--types-metadata <path> Optional datatype metadata from ncc c datatypes; repeat for dependencies outside the output directory.
--bsd <file> Legacy .bsd datatype definitions. Repeatable.
--internal-headers Compatibility no-op. SDK headers are selected at C compile time.
-v, --verbose Pass a verbosity level to the open62541 generator. Repeatable.

-h, --help shows command help. Relative paths resolve from the working directory. Optional file lists default to empty; -v defaults to zero occurrences. Split development headers are required; an open62541.h-only installation is unsupported.

Inputs and output

The input and every -e value are NodeSet XML files. Supply all dependencies, including transitive ones; open62541 does not accept o6\Python's bundled shorthand. SHORTNAME=PATH is accepted for dependencies, but only the path is used.

For one target, a valid C filename stem is preserved. Otherwise runs of non-ASCII identifier characters become underscores, surrounding underscores are stripped, and an empty result becomes model. A leading digit or keyword gets a model_ prefix. For example, Opc.Ua.Di.NodeSet2.xml becomes Opc_Ua_Di_NodeSet2. --shortname overrides this name; invalid explicit names are rejected. Names starting with underscores are reserved and are not accepted.

Pass several target XMLs to generate one pair and initializer, using an explicit shortname. Existing dependencies still provide context only. Names are not globally unique: use distinct shortnames for distinct models sharing an output directory. The output directory is created if missing and existing output files are replaced.

Generated API

UA_StatusCode ua_namespace_demo(UA_Server *server);

The actual function name follows the resolved shortname. Pass a valid server and check for UA_STATUSCODE_GOOD. Call generated dependencies first, in dependency order. The function registers namespace URIs and adds its own nodes; it does not add the dependency nodes declared by -e.

A failure can leave a partially populated server. Delete that server instead of continuing startup. Your application owns server cleanup.

Scripts and diagnostics

Exit status 0 means success; argument errors return 2. Other failures return nonzero, including statuses returned by the open62541 generator. Generated source is written to files. Generation logs can appear on standard output and errors on standard error; capture both when diagnosing failures. Treat diagnostics as human-readable messages, not a stable machine-readable format.

Symptom Fix
Invalid C identifier or include guard Supply a valid --shortname; input XMLs need not be renamed.
Missing model nodes during generation or registration Supply every dependency with -e and load its generated function first.
Missing SDK headers Add the SDK include directory containing open62541/server.h or open62541.h. See header selection.
Missing types_…_generated.h Match the types-array name to the datatype output basename.

Datatype options

ncc c datatypes [options] <outputFile>
Flag Meaning
<outputFile> Output path without extension. Required.
-c, --type-csv <file> CSV of type descriptions (node IDs). Repeatable.
-t, --type-bsd <file> .bsd file with type definitions. Repeatable.
-x, --xml <file> XML symbolic-name metadata; does not supply layouts. Repeatable.
-i, --import <TYPE_ARRAY#file.bsd> Types to load for resolution but not emit. Repeatable.
-s, --selected-types <file> One type name per line. Repeatable. Default: all parsed types.
--namespaceMap <index:uri> Set standalone datatype indexes by URI. Required for custom BSD namespaces; conflicting qualified CSV IDs are errors. Repeatable; namespace zero is predefined.
--opaque-map <file.json> JSON mapping of opaque type names to builtin types. Repeatable.
--no-builtin Do not emit the builtin types.
--internal The given .bsd files are internal types with no .csv.
--gen-doc Also write an .rst rendering of the type definitions.

cncc datatypes is an alias. Relative paths resolve from the working directory. Boolean flags default to off. The output directory is created if needed, and existing output files are overwritten. Generator failures return nonzero.

For example, an opaque-map file can map a model's Counter type to UInt32:

{
  "Counter": {"ns": 0, "id": 7, "name": "UInt32"}
}

Replace Counter with the opaque type declared by your model.

Coordinated models and CMake

ncc c model --help describes coordinated address-space, datatype, and NodeId header generation. See complete model generation. ncc c --cmake-dir prints the installed helper directory and exits successfully; see CMake integration for tracked builds and runtime requirements.

Standalone supporting commands

ncc c nodeids NodeIds.csv --prefix NS0 -o generated/ids.h
ncc c bsd MyModel.xml -o generated/MyTypes.bsd

These need only CSV or XML respectively. See standalone constants and BSD extraction for migration examples and validation rules. Both are also available through cncc.