Skip to main content
Version: Matrix OS 3.2

NVS API

Preview notice​

The MatrixOS Python API is in preview and is subject to change; it may contain errors.

Overview​

The NVS (Non-Volatile Storage) API in MatrixOS provides persistent storage for application data that survives device reboots. Data is stored using hash-based keys and can store arbitrary binary data. The NVS API is available as MatrixOS.NVS and is imported by default.

The Python NVS API is implemented in Applications/Python/PikaPython/MatrixOS_NVS.py with type hints in Applications/Python/PikaPython/_MatrixOS_NVS.pyi.

MatrixOS.NVS.GetSize​

def GetSize(hash: int) -> int

Gets the size of stored data for a given hash key.

Parameters:

  • hash (int): Hash key identifying the stored data

Returns:

  • int: Size of stored data in bytes, or 0 if not found

MatrixOS.NVS.GetVariable​

def GetVariable(hash: int) -> bytes

Retrieves stored data for a given hash key.

Parameters:

  • hash (int): Hash key identifying the stored data

Returns:

  • bytes: Stored data as bytes object, or empty bytes if not found

MatrixOS.NVS.SetVariable​

def SetVariable(hash: int, data: bytes) -> bool

Stores data with a given hash key.

Parameters:

  • hash (int): Hash key to identify the data
  • data (bytes): Data to store

Returns:

  • bool: True if successful, False on error

MatrixOS.NVS.DeleteVariable​

def DeleteVariable(hash: int) -> bool

Deletes stored data for a given hash key.

Parameters:

  • hash (int): Hash key identifying the data to delete

Returns:

  • bool: True if successful, False if key not found or error

Hash Key Guidelines​

  1. Uniqueness: Ensure hash keys don't collide between applications
  2. Consistency: Use the same key generation method throughout your app
  3. Namespacing: Consider using base offsets for different data types
  4. Documentation: Document your key allocation scheme

Storage Considerations​

  • Persistence: Data survives reboots and power cycles
  • Wear Leveling: NVS handles flash wear leveling automatically
  • Size Limits: Check device specifications for NVS capacity
  • Performance: NVS operations may have latency, avoid in time-critical code

Comments