.. _auto_physicaltest_import_bms_data:

*IMPORT DATA FROM BMS*
======================

Parses a Battery Management System (BMS) SSV file and ingests its channel data as a physical test record in d3VIEW. Optionally applies a policy-based channel-name mapping and a witness-run (WR) file to enrich the imported responses. Use this worker whenever raw BMS test data needs to be brought into the platform for downstream battery analysis.

When to use
-----------

Tagged: ``battery``, ``bms``, ``channel_mapping``, ``import``, ``physical_test``, ``protocol``, ``ssv``, ``witness_run``.

Inputs
------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20 20 20

   * - Label
     - ID
     - Type
     - Default
     - Required
     - Description
   * - Test Name
     - test_name
     - text
     - —
     - 
     - Optional human-readable label assigned to the created physical test record; leave blank to use the filename or a platform-generated default.
   * - BMS SSV File
     - bms_file
     - file
     - —
     - ✓
     - Required space-separated values (SSV) file exported from the BMS device; this is the primary data source containing all raw channel time-histories.
   * - WR File
     - wr_file
     - file
     - 0
     - 
     - Optional Witness Run (WR) file used to supplement or synchronise channels from the BMS file; leave as default (0) if no WR data is available.
   * - Protocol File
     - protocol_file
     - file
     - 0
     - 
     - Optional test protocol file that provides metadata or channel definitions for the BMS run; leave as default (0) if not applicable.
   * - Time Channel
     - time_channel
     - scalar
     - Test_Time
     - 
     - Name of the column in the SSV file that represents the time axis (default: 'Test_Time'); change only if the BMS export uses a different time-channel header.
   * - Channels To Save
     - channels_to_save
     - scalar
     - —
     - 
     - Comma-separated list of channel names to ingest; leave empty (default) to import all channels present in the SSV file.
   * - Skip Lines Every
     - points_increment
     - scalar
     - 40
     - 
     - Decimation factor — one data point is retained for every N rows (default: 40); increase to reduce dataset size, decrease for higher time resolution.
   * - Policy File
     - map_policies
     - file
     - —
     - 
     - Optional CSV/Excel policy file whose rows define expression-to-destination channel-name mappings; leave null to skip automated channel renaming.
   * - Expression Column
     - map_expression_header
     - scalar
     - Expression
     - 
     - Column header in the policy file that contains the source-channel match expression (default: 'Expression'); adjust if your policy file uses a different column name.
   * - Destination Column
     - map_destination_header
     - scalar
     - Destination
     - 
     - Column header in the policy file that contains the target channel name (default: 'Destination'); adjust if your policy file uses a different column name.
   * - Expression Map
     - responses_to_map
     - scalar
     - —
     - 
     - Filter expression (e.g. a glob or regex pattern) restricting which ingested responses are subject to policy mapping; leave empty to apply mappings to all responses.

Outputs
-------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 20

   * - Label
     - ID
     - Type
     - Description
   * - Physicaltest Id
     - physicaltest_id
     - integer
     - Integer primary key of the newly created physical test record in the d3VIEW platform; use this ID to reference the test in downstream workers.
   * - Num Responses
     - num_responses
     - integer
     - Total number of channel responses successfully ingested from the BMS SSV file into the physical test record.
   * - Num Mapped
     - num_mapped
     - integer
     - Count of ingested responses that were successfully renamed/mapped according to the supplied policy file.
   * - Num Unmapped
     - num_unmapped
     - integer
     - Count of ingested responses that did not match any policy rule and therefore retain their original BMS channel names.
   * - Policies
     - policies
     - dataset
     - Dataset representation of the loaded policy file rows, useful for auditing which mapping rules were applied during import.
   * - Mapped Responses
     - mapped_responses
     - dataset
     - Tabular dataset listing each response that was successfully mapped, including original and destination channel names.
   * - Unmapped Responses
     - unmapped_responses
     - dataset
     - Tabular dataset listing each response that could not be matched to a policy rule, flagging channels that may need manual renaming.
   * - Logs
     - logs
     - dataset
     - Structured log dataset capturing warnings, errors, and informational messages produced during the BMS import and mapping process.

Disciplines
-----------

- data.dataset.ingest
- data.io.file
- engineering.battery

.. raw:: html

   <hr style="margin-top:2em">
   <p style="font-size:11px;color:#888">
   Auto-generated from <code>platform</code> schema. Worker id: <code>physicaltest_import_bms_data</code>. Schema hash: <code>5e7e47df1c88</code>. Hand-curated docs in <code>workerexamples/</code> override this page when present.
   </p>