Skip to content

Installation

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

Installation Guide

Requirements

  • MATLAB R2020b+ or GNU Octave 7+
  • Optional: C compiler for MEX acceleration (macOS: Xcode CLT, Linux: GCC, Windows: MSVC)
  • No external toolbox dependencies

Setup

Step 1: Download & Initialize

Clone or download the FastSense repository, then run the installer:

cd /path/to/fastsense
install

This command:

  • Adds all library paths (libs/FastSense, libs/SensorThreshold, libs/EventDetection, libs/Dashboard, libs/WebBridge)
  • Initializes the Tag registry and theme cache
  • (Optionally) compiles MEX accelerators if a C compiler is detected

Step 2: Verify Installation

Run the test suite to confirm everything is working:

addpath('tests')
run_all_tests()

Expected output: ~85 tests passing on MATLAB, ~70 tests passing on Octave (some platform-specific skips). Or run a quick visual demo:

example_basic

This renders a 10M-point sine wave with thresholds and violation markers in ~2 seconds.

MEX Acceleration (Optional)

The core downsampling and violation detection functions have optional C implementations with SIMD intrinsics (AVX2/NEON) that deliver 3–50× speedups. If MEX files are not compiled, pure-MATLAB fallbacks are used automatically.

Compile MEX Manually

cd libs/FastSense
build_mex

Auto-detection:

  • arm64 (Apple Silicon, ARM servers): NEON intrinsics
  • x86_64 (Intel/AMD): AVX2 with SSE2 fallback
  • Octave compatibility: Tested on Octave 7–11 with bundled SQLite3

Accelerated functions:

  • binary_search_mex — viewport clipping lookup (10–20× faster)
  • minmax_core_mex — per-pixel MinMax downsampling (3–10×)
  • lttb_core_mex — LTTB curve-preserving downsampling (10–50×)
  • violation_cull_mex — fused violation detection + pixel culling
  • build_store_mex — SQLite bulk write (10–20× faster)
  • mksqlite — SQLite C bindings for DataStore

If a compiler is not available or compilation fails, the library falls back gracefully to pure-MATLAB implementations with identical behavior.

Installation Methods

Method 1: Package Manager (pip for Python Bridge)

If you're using the Python WebBridge component:

pip install fastsense-bridge
python -m fastsense_bridge --matlab-port 9001 --host localhost --port 8000

This installs and runs the Python FastAPI server that connects to MATLAB's TCP bridge.

Method 2: From Source (Git Clone)

git clone https://github.com/yourorg/fastsense.git
cd fastsense
matlab -nojvm -nodisplay -r "install; exit"

Method 3: Docker (Optional)

A pre-built Docker image includes Octave + FastSense + compiled MEX:

docker run -it ghcr.io/yourorg/fastsense:latest
octave --eval "install; run_all_tests"

Architecture Overview

graph TB
    A["FastSense<br/>(Core Plotting)"] -->|renders| B["Dashboard Engine<br/>(Widgets & Layouts)"]
    A -->|monitors| C["SensorThreshold<br/>(Tag-based Sensors)"]
    C -->|detects| D["EventDetection<br/>(Violation Events)"]
    B -->|exposes via| E["WebBridge<br/>(REST/WebSocket)"]
    F["Python Bridge"] -.->|queries| E
    style A fill:#fffacd
    style B fill:#f5f5dc
    style C fill:#e6d7ff
    style D fill:#ffe6cc
    style E fill:#cce5ff
Loading
Library Directory Purpose
FastSense libs/FastSense/ Ultra-fast time-series plotting with downsampling & caching
SensorThreshold libs/SensorThreshold/ Tag-based sensors with state-dependent thresholds
EventDetection libs/EventDetection/ Violation detection, event storage, Gantt timelines
Dashboard libs/Dashboard/ Widget layouts, responsive grid, JSON serialization
WebBridge libs/WebBridge/ TCP server for web & external clients

Platform-Specific Notes

MATLAB R2020b

  • Native support for all features
  • MEX compilation requires MATLAB Coder or a standalone C compiler
  • datetime X-axis formatting is automatic

GNU Octave 7–11

  • All core features supported (FastSense, Dashboard, EventDetection)
  • MEX compilation: sudo apt-get install octave-dev (Linux) or Homebrew (macOS)
  • WebBridge uses Octave's HTTP client (no external server dependency)
  • Some graphics quirks: uicontrol buttons may not render in headless mode; use headless export flags for automated dashboards

macOS (Apple Silicon)

  • MEX auto-detects ARM64 and uses NEON intrinsics
  • Xcode Command Line Tools required: xcode-select --install

Windows

  • MSVC compiler required: Install Visual Studio Build Tools
  • Path handling: Use forward slashes in file paths or raw strings "C:\path" (not 'C:\path')

Linux (x86_64, ARM64)

  • GCC auto-detects AVX2 (x86_64) or NEON (ARM64)
  • On Ubuntu: sudo apt-get install build-essential

Troubleshooting

MEX Compilation Fails

Symptom: build_mex() errors with compiler not found or syntax error.

Solution:

  1. Verify compiler is installed: 
    mex -setup  % MATLAB
mkoctfile --version  % Octave
  2. If not installed, download:
    • macOS: xcode-select --install
    • Linux: sudo apt-get install build-essential
    • Windows: Visual Studio Build Tools (MSVC)
  3. Re-run build_mex()

Fallback: If compilation fails, pure-MATLAB implementations are used automatically. Performance is ~3–10× slower but fully functional.

mksqlite Errors (DataStore Operations)

Symptom: Undefined function 'mksqlite' when using disk-backed storage.

Solution:

  1. Ensure MEX is compiled: build_mex()
  2. Verify SQLite3 is available (bundled in libs/FastSense/private/mex_src/sqlite3.c)
  3. On Octave, check MEX support: mkoctfile --version

Fallback: DataStore operations revert to all-in-memory mode (warning issued).

Test Suite Failures (Octave)

Symptom: A few tests fail with "object deletion" crashes on Octave 8–10.

Solution: Upgrade to Octave 11.1.0 (released 2026-02-18), which fixes upstream bug #67749. Alternatively, use MATLAB R2020b+ which has no such issue.

Dashboard Widgets Don't Render

Symptom: DashboardEngine.render() opens figure but widgets appear blank.

Solution:

  1. Verify display is available: ~isempty(get(0, 'CurrentFigure'))
  2. On headless systems, use flag: install('SKIP_GRAPHICS', true) and work with data-only APIs
  3. Check MATLAB version: R2020b or later required
  4. Force a redraw: drawnow('expose')

Next Steps

  1. Getting-Started — Step-by-step tutorial with your first 10M-point plot
  2. Examples — Explore 80+ categorized runnable examples
  3. API-Reference:-FastSense — Learn the core plotting API
  4. Performance — Understand optimization techniques and benchmarks

Support & Contribution

Happy plotting! 📊

FastSense Wiki

API Reference

Guides

Use Cases

Internals

Resources

Clone this wiki locally