OASIS Board Python Package

Used in the following packages:

• oasis-gui
• oasis-tui

                    +-------------------+
                    |     oasis-api     |
                    |  (Python library) |
                    +-------------------+
                             ^
         +-------------------+---------------------+
         |                   |                     |
  +----------------+   +----------------+   +----------------+
  |   oasis-cli    |   |   oasis-tui    |   |   oasis-gui    |
  | (flags & args) |   | (guided menus) |   | (desktop/web)  |
  +----------------+   +----------------+   +----------------+

HDF5 File Format for OASIS Measurements

Overview

Measurement data is stored in HDF5 files in a tidy data format, making it easy to analyze, visualize, and share.

Structure

• The main dataset is stored at the root as /data.
• The file contains attributes describing metadata and the measurement setup.

Data Table: /data

• Shape: (N, ) where N = number of channels × number of time points

• Each row represents a single observation:

  • channel: Integer (1–8), channel number
  • time: Float (seconds), timestamp of the sample
  • signal: Float (volts), measured signal value

Example (first few rows):

• Units:

  • The signal column is stored in volts.

File Attributes (Metadata)

• schema_version: HDF5 schema version used by the file
• duration_s: Duration of acquisition (in seconds)
• sampling_frequency_hz: Sampling frequency (in Hz)
• voltage_ranges: Array of voltage ranges for each channel (in volts)
• channels: Number of channels (typically 8)
• board_count: Number of contributing boards in the file
• channels_per_board: Channel counts per contributing board
• format description: Human-readable schema description
• Merged files additionally store source_files, source_labels, and merge_align_mode

Why Tidy Data?

• Each variable forms a column: channel, time, signal
• Each observation forms a row: one reading from one channel at one time
• Each type of observational unit forms a table: all data is in /data
• This format makes the data easy to filter, aggregate, and visualize in Python (Pandas), R, MATLAB, etc.

How to Read the File (Python Example)

import h5py
import numpy as np

with h5py.File("measurement.h5", "r") as f:
    data = f["data"][:]
    print("Fields:", data.dtype.names)  # ('channel', 'time', 'signal')
    print("First row:", data[0])
    print("Sampling frequency:", f.attrs["sampling_frequency_hz"])
    print("Voltage ranges:", f.attrs["voltage_ranges"])

Viewing

• Use HDFView or Vitables to inspect your data and metadata visually.

Compatibility

• oasis-api v4.0.0-b1 targets OASIS firmware v4 boards.
• Stored serial acquisitions require USB CDC+MSC firmware support (>= 4.0.0.a2).
• The current serial acquisition path does not support legacy v3 CDC payload transfer boards.
• load_h5() expects the current tidy schema with the signal field; legacy v3 HDF5 files written with voltage are not supported by this release.

Device Information

Device information is written with one direct API call; the firmware no longer opens an interactive serial menu for OASIS.SetDeviceInfo().

board.set_device_info(
    architecture_id=2,  # 0=Original OASIS, 1=OASIS-UROS, 2=OASIS-ERIS
    hw_major=1,
    hw_minor=0,
    adc_bits=18,
    teds=0,
    wss=0,
    device_name="OASIS-01",
)

Distributed Acquisition Helpers

OasisBoard now includes helpers for multi-board distributed workflows:

• This release line is intended for firmware v4 boards.

• Stored acquisitions in mode="serial" require firmware >= 4.0.0.a2 on OASIS USB CDC+MSC devices.

• Measurement payload is copied from USB MSC volumes, not transferred over CDC.

• Live streaming remains CDC-based.

• acquire(...)

  • Standard acquisition call; on firmware >= 4.0.0.a2 this also performs one-wire distributed primary-board signaling automatically.

• collect_distributed_serial_files(...)

  • Copies .OASISraw/.OASISmeta from multiple board-specific USB MSC volumes and writes local files.

• stack_distributed_measurements(...)

  • Loads multiple distributed files and stacks them into a single array.

• collect_and_stack_distributed(...)

  • One-shot helper for USB MSC collection by board serial port + optional manual file sources + stacking.

• merge_h5_files(...)

  • Merges multiple OASIS .h5 files into one consistent dataset with global channel numbering.
  • Stores merge metadata (board_count, channels_per_board, source_files, source_labels).

Example:

from oasis_api import OasisBoard

primary = OasisBoard(mode="serial", port="/dev/cu.usbmodem11101", baudrate=1000000)
resolved = "dist_run"
primary.acquire(t_sample=0.25, f_sample=2000, custom_filename=resolved)

result = primary.collect_and_stack_distributed(
    filename=resolved,
    serial_ports=["/dev/cu.usbmodem11101", "/dev/cu.usbmodem11201"],
    t_sample=0.25,
    f_sample=2000,
    output_dir="./distributed_pull",
)

stacked = result["stacked"]      # (n_devices, 8, n_samples)
flattened = result["flattened"]  # (n_devices*8, n_samples)

Merge Existing H5 Files

from oasis_api import OasisBoard

result = OasisBoard.merge_h5_files(
    input_files=["board1.h5", "board2.h5"],
    output_file="merged.h5",
    align="truncate",  # or "pad"
    overwrite=True,
)
print(result)

Merged files can be loaded and plotted without prior knowledge of board count:

board = OasisBoard(mode="offline")
board.load_h5("merged.h5")
board.plot_data()  # adapts to total channel count with board-aware labels (e.g. board_1:CH1)