Current Print Workflow

This document describes the actual print workflow across the C client, C SDK, and tijet_1/tincore gRPC server.

This document only describes the current codebase and client behavior, and does not include future refactoring plans.

Source Baseline

Participants

Current Call Sequence

sequenceDiagram
    autonumber
    participant Caller as Caller
    participant Callee as Callee

    Caller->>Callee: tijet_client_set_event_callback(callback, user_data)
    Callee-->>Caller: Callback registered

    Caller->>Callee: tijet_client_start_event_subscription()
    Callee-->>Caller: TIJET_OK
    Note over Callee: Background event thread created
    Note over Callee: SubscribeEvents() polling

    Caller->>Callee: tijet_client_set_print_data(data, index, is_static)
    Callee-->>Caller: SetPrintDataResponse{success=true}
    Note over Callee: Print data enters background processing
    Note over Callee: DATA_READY may still be 0 on return

    loop START_PRINT retry, total timeout 10s
        Caller->>Callee: tijet_client_print_control(START_PRINT)
        alt DATA_READY == 0
            Callee-->>Caller: TIJET_ERR_SERVER
            Note over Caller: Wait 1s before retry
        else DATA_READY != 0
            Callee-->>Caller: TIJET_OK
            Note over Callee: High-voltage thread created
        end
    end

    Note over Caller: After START_PRINT success, wait for PrintStarted

    alt High voltage successful
        Callee-->>Caller: PrintStarted{success=true}
        Note over Caller: Ready for printing
    else High voltage failed
        Callee-->>Caller: PrintStarted{success=false}
        Note over Caller: Failure, message contains failed head count
    else PrintStarted not received within 10s
        Note over Caller: Timeout
    end

Retry & Timeout Flow

flowchart TD
    A["Caller: Connect to server"] --> B["Caller: Register callback<br/>Start event subscription"]
    B --> C["Caller: set_print_data() upload print data"]
    C --> D{"Callee: Upload RPC successful?"}

    D -->|"No"| D1["Failed, flow ends"]
    D -->|"Yes"| E["Callee: Data enters background processing<br/>DATA_READY may still be 0"]

    E --> F["Caller: Start START_PRINT retry timer"]
    F --> G["Caller: print_control(START_PRINT)"]
    G --> H{"Callee: Is DATA_READY == 0?"}

    H -->|"Yes: data not ready"| I{"Total retry time reached 10s?"}
    I -->|"No"| J["Caller: Wait 1s"]
    J --> G
    I -->|"Yes"| K["Failed: Print data preparation timeout"]

    H -->|"No: data ready"| L["Callee: Create high-voltage thread<br/>Return TIJET_OK"]
    L --> M["Caller: Wait for PrintStarted event<br/>timeout 10s"]
    M --> N{"Result"}

    N -->|"success=true"| O["Success: High voltage enabled<br/>Ready for printing"]
    N -->|"success=false"| P["Failed: High voltage activation failed"]
    N -->|"Timeout"| Q["Failed: High voltage activation timed out"]

Current Return Value Semantics

Source Index

C SDK

• sdk/c/src/tijet_core.cpp:342: tijet_client_set_print_data().
• sdk/c/src/tijet_core.cpp:396: Register event callback.
• sdk/c/src/tijet_core.cpp:408: Start event subscription and create event thread.
• sdk/c/src/tijet_core.cpp:641: tijet_client_print_control().
• sdk/c/src/tijet_core.cpp:655: Match START_PRINT and call StartPrint RPC.
• sdk/c/include/tijet_core.h:441: Print data upload C API declaration.
• sdk/c/include/tijet_core.h:480: Event callback registration C API declaration.
• sdk/c/include/tijet_core.h:500: Event subscription C API declaration.
• sdk/c/include/tijet_core.h:650: Print control C API declaration.

Proto Contracts

• proto/print.proto:7: SetPrintDataRequest.
• proto/print.proto:19: StartPrintRequest.
• proto/print.proto:22: StartPrintResponse.
• proto/event.proto:48: PrintDataStatus.
• proto/event.proto:53: PrintStarted.
• proto/tincore.proto:27: SetPrintData RPC.
• proto/tincore.proto:28: StartPrint RPC.
• proto/tincore.proto:33: SubscribeEvents RPC.

tijet_1/tincore gRPC Server

The following paths are relative to the feature-grpc-cpp branch of tijet_1/tincore:

• src/grpc/tincore_service_impl.cpp:210: Receives SetPrintData client stream.
• src/grpc/default_tin_core_handlers.cpp:211: Passes print data to gAFBridge->writePrintData().
• src/grpc/tincore_service_impl.cpp:130: Handles StartPrint RPC.
• src/grpc/default_tin_core_handlers.cpp:370: Synchronously checks PARAM_INDEX_RO_DATA_READY.
• src/grpc/default_tin_core_handlers.cpp:386: Enables driver board power and high voltage in background.
• src/grpc/tincore_service_impl.cpp:237: Handles SubscribeEvents server stream.
• src/grpc/tincore_service_impl.cpp:285: Maps internal printStarted JSON to EventReport.print_started.

Known Issues

1. The C SDK header examples use lowercase "start_print", but the implementation only matches uppercase "START_PRINT". Clients following the header example will receive TIJET_ERR_INVALID_ARG.
2. When tijet_client_set_print_data() returns TIJET_OK, print data may still be processing in gAFBridge background; this cannot be used to determine data readiness.
3. Proto defines PrintDataStatus, but the current server does not generate or map this event. Clients cannot use this event to wait for data readiness.
4. The C SDK does not check SetPrintDataResponse.success — it only checks the gRPC Status. If the RPC status is OK but the response success=false, the C SDK still returns TIJET_OK.
5. The current client retries every second for all START_PRINT failures, without distinguishing between insufficient buffer data, RPC failure, or other server errors.
6. START_PRINT returning TIJET_OK only means the server created a background thread; the final high-voltage result must be obtained from the independent PrintStarted event.
7. There is no request ID or other correlation field between StartPrintResponse and PrintStarted.
8. PrintStarted depends on event subscription being established; without a valid subscription, the background thread will not deliver the final result to this client.
9. tijet_client_start_event_subscription() returns immediately after creating the event thread, without waiting for the server to complete SubscribeEvents setup. This creates a time window between “subscription start returned success” and “server can push events.”