nexatom-downloads

Device Connection and State

Once a nexatom_tt_handle has been allocated via nexatom_tt_create (see Section 7.3), these functions manage the physical USB session, execute the initial handshakes with the FPGA, and expose hardware capabilities.

This module also provides deterministic checks for the FPGA bootloader state (nexatom_tt_get_hardware_protocol_mode) and internal state machine queries (nexatom_tt_get_state), which are critical for robust error recovery.

Function Reference

Function	Parameters (In/Out)	Returns	Description
`nexatom_tt_connect`	`[In] nexatom_tt_handle device` `[In] uint32_t timeout_ms`	`nexatom_error_code_t`	Opens exactly the board at the handle’s `connection_id` and waits until it can be controlled: transport open, first telemetry seen, control authority granted. A board in bootloader mode returns once the transport is open. `timeout_ms` bounds the whole call. Use runtime connect for measurement.
`nexatom_tt_connect_runtime`	`[In] nexatom_tt_handle device` `[In] uint32_t timeout_ms`	`nexatom_error_code_t`	Native discovers runtime/service, boots an existing valid slot when needed and waits for authorized runtime readiness on this handle.
`nexatom_tt_disconnect`	`[In] nexatom_tt_handle device`	`nexatom_error_code_t`	Closes the USB session without freeing host memory. Every wait is bounded and in-flight data is dropped, not drained; finish file saving first. Also turns automatic reconnection off until the next successful connect.
`nexatom_tt_set_auto_reconnect`	`[In] nexatom_tt_handle device` `[In] bool enable`	`nexatom_error_code_t`	Off by default. When on, re-establishes a working link that dropped, to the same `connection_id` and the same instrument only. Never opens the first connection.
`nexatom_tt_get_device_info`	`[In] nexatom_tt_handle device` `[Out] nexatom_tt_info_t* info`	`nexatom_error_code_t`	Retrieves the string metadata (`connection_id`, FT601 serial, firmware version) for the handle’s board.
`nexatom_tt_get_capabilities`	`[In] nexatom_tt_handle device` `[Out] nexatom_tt_capabilities_t* capabilities`	`nexatom_error_code_t`	Returns native capability values; combine these with the authorized device profile rather than treating them as measured physical specifications.
`nexatom_tt_is_connected`	`[In] nexatom_tt_handle device` `[Out] bool* is_connected`	`nexatom_error_code_t`	Queries if the physical USB session is currently established.
`nexatom_tt_get_state`	`[In] nexatom_tt_handle device` `[Out] nexatom_tt_state_t* state`	`nexatom_error_code_t`	Retrieves the active software driver state (e.g., `CONNECTED`, `ACQUIRING`, `ERROR`).
`nexatom_tt_get_hardware_protocol_mode`	`[In] nexatom_tt_handle device` `[Out] nexatom_hardware_protocol_mode_t* mode`	`nexatom_error_code_t`	Crucial diagnostic query. Returns whether the hardware is running the `RUNTIME` (data) or `BOOTLOADER` (flashing) image.

Data Structures & Enums

`nexatom_tt_state_t` (Enum)

Represents the internal state machine of the C++ driver backing the nexatom_tt_handle.

0: DISCONNECTED
1: CONNECTING
2: CONNECTED (Idle)
3: CONFIGURING
4: ACQUIRING (Data flowing)
5: STOPPING
6: ERROR (Requires teardown)

`nexatom_hardware_protocol_mode_t` (Enum)

Directly maps to the FPGA bitstream identity currently executing on the hardware.

0: UNKNOWN (Detecting or unpowered)
1: RUNTIME (Standard measurement mode)
2: BOOTLOADER (Recovery and flashing mode)

`nexatom_tt_capabilities_t` (Struct)

C Example: Connecting and Verifying Hardware

nexatom_tt_state_t state;
nexatom_hardware_protocol_mode_t mode;
nexatom_tt_capabilities_t caps;

// Fragment: my_device is created and its owner handles cleanup on every exit.
if (nexatom_tt_connect_runtime(my_device, 20000) == NEXATOM_SUCCESS) {
    
    // 2. Ensure we are in RUNTIME mode before measuring
    if (nexatom_tt_get_hardware_protocol_mode(my_device, &mode) != NEXATOM_SUCCESS)
        return -1;
    if (mode != NEXATOM_HARDWARE_PROTOCOL_MODE_RUNTIME) {
        printf("ERROR: Runtime is not ready.\n");
        nexatom_tt_disconnect(my_device);
        return -1;
    }

    // 3. Extract the device limits
    if (nexatom_tt_get_capabilities(my_device, &caps) != NEXATOM_SUCCESS)
        return -1;
    printf("Connected! Native Resolution: %u ps\n", caps.time_resolution_ps);
    printf("Supported Channels: %u\n", caps.num_channels);
    
    // 4. Verify state machine
    if (nexatom_tt_get_state(my_device, &state) != NEXATOM_SUCCESS)
        return -1;
    if (state == NEXATOM_STATE_CONNECTED) {
        printf("Device is idle and ready for configuration.\n");
    }
}

Profile and application contract

Before measurement use nexatom_tt_get_device_profile_v1(device, &profile). Initialize struct_size and struct_version with the matching header constants. Inspect control/service flags, effective_public_tdc_mask, supported output mask, feature flags, max_channel_input_delay_ps and test-pulse clock/bounds. A state enum or physical channel count is not a substitute for authority.

For example, after runtime connection, check that the intended two inputs and processed output are available before configuring them:

// Fragment inside the acquisition owner; return/failure still goes through its cleanup.
nexatom_tt_device_profile_v1_t profile = {0};
profile.struct_size = sizeof(profile);
profile.struct_version = NEXATOM_TT_DEVICE_PROFILE_V1_VERSION;
nexatom_error_code_t rc = nexatom_tt_get_device_profile_v1(my_device, &profile);
if (rc != NEXATOM_SUCCESS)
    return -1;

const uint32_t wanted_channels = (1u << 0) | (1u << 1);
if (!(profile.profile_flags & NEXATOM_TT_PROFILE_CONTROL_AUTHORIZED) ||
    (profile.profile_flags & NEXATOM_TT_PROFILE_IN_SERVICE) ||
    (profile.effective_public_tdc_mask & wanted_channels) != wanted_channels ||
    !(profile.supported_output_mode_mask & (1u << NEXATOM_OUTPUT_REALTIME_DATA))) {
    fprintf(stderr, "This runtime cannot perform the requested acquisition.\n");
    return -1;
}
// Also check the feature bit for each engine you intend to enable.

nexatom_tt_get_application_contract exposes native’s resolved application contract. nexatom_tt_apply_inventory_profile_v1, nexatom_tt_apply_manual_profile_v1, nexatom_tt_clear_profile_evidence_v1, nexatom_tt_configure_runtime_compatibility and nexatom_tt_set_bootloader_probe_enabled are controlled compatibility tools, not ordinary startup prerequisites. Use their exact declarations from the header; do not override an unknown model by guessing capabilities.

Connection errors and several boards

nexatom_tt_connect() opens exactly the board at the handle’s connection_id (see board identity). It never falls back to another board. When it fails, nexatom_tt_get_last_error_message() names the cause, for example Device not found: no FT601 at USB port … or … already open …. Several boards can be connected at once through separate handles.

Automatic reconnection

// Fragment: my_device is connected; on_status is the application's handler.
nexatom_tt_set_connection_status_callback(my_device, on_status, app_state);
nexatom_tt_set_auto_reconnect(my_device, true);

nexatom_tt_set_auto_reconnect() is the explicit opt-in for retrying in the background after a working link goes away, which is what a cable pull looks like. It is off by default. It never opens the first connection: until a nexatom_tt_connect() has succeeded there is nothing to re-establish, and an explicit nexatom_tt_disconnect() turns the retries off until the next successful connect. Registering the connection status callback only observes the connection; it does not open or reopen one.

A reconnect goes only to the same connection_id (the same USB port), never to another board. When the reconnected board reports its identity, the SDK compares product model, hardware revision and the instrument serial from telemetry with the instrument that the explicit connect saw; the FT601 USB serial is never used. If another instrument now sits in that port, the SDK refuses it: the handle is not marked ready, it is disconnected, the retries stop, and the error (beginning Auto-reconnect refused:) names both instruments. An explicit nexatom_tt_connect() accepts whichever instrument is in the port and makes it the one later reconnects must match. Readiness after a reconnect is reported through the connection status callback.

Use the complete C/C++ acquisition templates for checked cleanup on every failure path. Connection success does not itself enable the application’s measurement.