Skip to content

Installation

Jump to bottom
github-actions[bot] edited this page Apr 3, 2026 · 12 revisions

Installation

Prerequisites

System Requirements

  • MATLAB R2020b+ or GNU Octave 7+
  • C compiler (optional but recommended for 3-50x performance boost):
    • macOS: Xcode Command Line Tools (xcode-select --install)
    • Linux: GCC (sudo apt-get install build-essential on Ubuntu/Debian)
    • Windows: MSVC (included with Visual Studio 2017+) or MinGW
  • No MATLAB toolboxes required — FastSense is pure MATLAB/Octave

Supported Platforms

  • Linux (x86_64, ARM64)
  • macOS (Intel x86_64, Apple Silicon ARM64)
  • Windows (x86_64, native or WSL)

Runtime Versions

Component Minimum Version Notes
MATLAB R2020b Named arguments, categorical arrays
Octave 7.0 GUI toolkit (qt), handle class support
Python (WebBridge only) 3.11+ FastAPI, Uvicorn, async support

Installation Methods

Method 1: Package Manager Install (Recommended)

MATLAB File Exchange

% Coming soon: matlab.codeexchange or File Exchange
% For now, use Method 2 (Source)

Homebrew (macOS/Linux)

# Coming soon: brew install fastsense

Octave Package Manager

% Install from Octave Forge (coming soon)
pkg install -forge fastsense

Method 2: Install from Source (Current)

Clone Repository

git clone https://github.com/HanSur94/FastSense.git
cd FastSense

Run Installation Script

% In MATLAB or Octave
install;

This script:

  • Adds all library paths to path
  • Attempts MEX compilation if C compiler is detected
  • Verifies all core classes are accessible
  • Performs JIT warmup on first plot

Manual path setup (alternative):

addpath(genpath('/path/to/FastSense/libs'));
addpath(genpath('/path/to/FastSense/examples'));
addpath(genpath('/path/to/FastSense/tests'));

Method 3: Docker Setup

Build Image

docker build -t fastsense:latest .
docker run -it fastsense:latest /bin/bash

Run Example in Container

docker run --rm fastsense:latest octave --eval "install; example_basic"

Optional: MEX Acceleration

FastSense includes optional C MEX implementations with SIMD intrinsics for high-performance downsampling and threshold detection. MEX is optional—pure-MATLAB fallbacks are always available.

Build MEX Files

install;  % Run once to set paths
cd libs/FastSense
build_mex;

Output:

Compiling binary_search_mex.c (x86_64, AVX2)...
Compiling minmax_core_mex.c (x86_64, AVX2)...
Compiling lttb_core_mex.c (x86_64, AVX2)...
Compiling violation_cull_mex.c (x86_64, AVX2)...
MEX build complete. 4/4 files compiled successfully.

Troubleshooting MEX Compilation

Error Solution
"mex: command not found" Install a C compiler (see Prerequisites)
"Warning: SIMD disabled (AVX2 not supported)" Normal on older CPUs—MEX will use SSE2 or scalar fallback
"Error: MEX compilation failed" Check compiler: mex -setup (MATLAB) or mkoctfile --version (Octave)
MEX file crashes during runtime Try build_mex clean and rebuild; file a bug report

Verify MEX Status

% Check which MEX files are compiled
ls libs/FastSense/private/*.mexa64      % Linux
ls libs/FastSense/private/*.mexmaci64   % macOS Intel
ls libs/FastSense/private/*.mexw64      % Windows
ls libs/FastSense/private/*.so          % Octave on Linux

% If MEX files exist, they will be auto-detected and used
% If missing, pure-MATLAB fallbacks run automatically

Performance Impact

Approximate speedup over pure MATLAB (varies by data size and CPU):

Function Speedup When Used
binary_search_mex 10–20x Every zoom operation
minmax_core_mex 3–10x First render + extreme zoom
lttb_core_mex 10–50x First render + zoom
violation_cull_mex 5–15x Threshold rendering

On a 50M-point dataset: ~4.7s render with MEX vs. ~30s pure MATLAB.

Verification Steps

1. Verify Core Installation

install;

% Check that all key classes are accessible
which FastSense         % Should return path to FastSense.m
which Sensor            % Should return path to Sensor.m
which DashboardEngine   % Should return path to DashboardEngine.m
which EventDetector     % Should return path to EventDetector.m

If any which command returns "not found", the paths were not added correctly. Run install again.

2. Run Quick Example

install;
example_basic;

You should see:

  • A MATLAB figure with a plot of ~10M noisy sine wave points
  • Red and orange dashed horizontal threshold lines
  • Interactive zoom/pan with smooth performance
  • Close the figure to exit

3. Run Unit Tests

install;
addpath('tests');
run_all_tests;

Expected output:

MATLAB Test Suite
Running TestAddLine ... OK
Running TestAddThreshold ... OK
...
=====================================
Passed: 247/250 | Failed: 3 | Skipped: 5

Note: A few tests may be skipped on Octave (those requiring PostSet listeners or App Designer) or fail if optional dependencies are missing.

4. Run Examples

install;
addpath('examples');
run_all_examples;  % Runs all 80+ examples sequentially

Or run a specific example:

example_dashboard;        % Multi-tile dashboard
example_sensor_todisk;    % Disk-backed 100M-point data
example_live_pipeline;    % Real-time event detection

5. Verify MEX (Optional)

% Compile and verify MEX files
build_mex;

% Check performance gain
benchmark_zoom;  % Renders 10M points at 5 zoom levels

Post-Install Configuration

Set Default Theme

% Persistent config (survives MATLAB restarts)
defaults = FastSenseDefaults();
defaults.ThemeName = 'dark';  % or 'light', 'industrial', 'scientific'
setdefaults(defaults);

Configure Live Mode Interval

% Poll for new data every 2 seconds (default: 5)
d = DashboardEngine(...);
d.LiveInterval = 2;

Enable Verbose Logging

d.Verbose = true;  % Prints progress and errors to console

Troubleshooting

"License number mismatch" (MATLAB)

This is a MATLAB license warning, not a FastSense issue. Ignore safely.

"Cannot connect to display" (Octave on headless server)

Use Xvfb (X virtual framebuffer):

xvfb-run -a octave --eval "install; example_basic"

"Out of memory" on large datasets

Use disk-backed storage:

s = Sensor('X', X, 'Y', Y);
s.toDisk();  % Automatically uses SQLite storage

Slow performance even with MEX compiled

Check MEX file architecture matches your MATLAB:

computer         % Check: GLNXA64 (Linux), MACI64 (Intel Mac), etc.
ls libs/FastSense/private/*mexa64  % Should match architecture

"Undefined function" errors after install

Restart MATLAB/Octave completely (not just clear all).

Next Steps

  1. Quick Start: Read the Getting Started Guide
  2. API Reference: Browse FastSense API, Dashboard API, Sensors API
  3. Live Mode: See Live Mode Guide for real-time data monitoring
  4. Dashboard: Build interactive dashboards with Dashboard Engine Guide
  5. Examples: Explore 80+ working examples

Support

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally