Code Overview

⌘K
  2. Home
  4. Docs
  6. Code Overview
  8. Remote Memory Access & BOS Variables

Remote Memory Access & BOS Variables

What is Remote Memory Access?

Remote Memory Access is a powerful capability in BOS that enables any module within a networked array to directly read from or write to another module’s RAM or Flash memory. This is accomplished using dedicated BOS messages and APIs. The accessed memory may contain variables, flags, control states, or other runtime data. By providing direct access to remote modules’ memory, this mechanism eliminates the need for complex communication protocols.

Key advantages include:

  • Real-time synchronization of operational states and data across modules.
  • Granular control over internal variables in distributed systems.
  • Efficient data sharing without polling or redundant messaging.

What are BOS Variables?

Typically, accessing a variable in another module requires knowledge of its physical memory address (e.g., 0x20000100). BOS simplifies this through BOS Variables: RAM-based virtual variables mapped to physical memory locations via simple index values (e.g., 1, 2, …, N).

Key characteristics:

  • Declared with volatile to permit external updates.
  • Registered via AddBOSvar().
  • Remotely accessible via BOS APIs without physical address knowledge

Example:
A module registers a local variable as “BOS Variable 1”. Any module in the array can then read/write this variable using its index.

Note:

Each module supports up to 30 registered BOS Variables ⚠️

Remote Functions:

Below are the main functions used for remote memory operations.
1) AddBOSvar() – Registering a BOS Variable

✅ AddBOSvar():

AddBOSvar(format, address);

Parameter:

  • format: Variable data format (e.g., FMT_UINT8).
  • address: Local RAM address of the variable.

Must be called on the destination module before accessing the variable remotely.
Example:
uint8_t var;
AddBOSvar(FMT_UINT8, (uint32_t)&var);

2) WriteRemote:
✅ WriteRemote() – Writing to Remote Memory or BOS Variable.

This function writes a value to a neighbor module within the array.

WriteRemote(dstModuleID, localVarAddress, remoteVarAddress, format, timeout);

Parameter Breakdown:

  • dstModuleID: ID of the module to receive the data.
  • localVarAddress: Address of the local variable to send (e.g., (uint32_t)&var).
  • remoteVarAddress: Either:
    – A virtual BOS Variable index (e.g., 1, 2, etc.), or
    – A raw memory address on the destination module (e.g., 0x2000001C).
  • format: The data type format (e.g., FMT_UINT8, FMT_FLOAT).
  • timeout: Max wait time for the operation (0xFFFF for infinite).

The function internally detects whether the remoteVarAddress points to a raw address or a BOS
Variable index based on context.

Example 1: Writing to Raw Memory Address

Module 1 writes a variable to a precise memory location in the destination module (Module 2).

// Module 1 code:
volatile uint8_t var = 75;
WriteRemote(2, (uint32_t)&var, 0x2000001C, FMT_UINT8, 0xFFFF);

Example 2: Writing to BOS Variable Index

Module 1 writes a variable to BOS Variable list in the destination module (Module 2).

// Module 1 code :
volatile uint8_t var = 50;
WriteRemote(2, (uint32_t)&var, 1, FMT_UINT8, 0xFFFF);

// Module 2 code :
volatile uint8_t var;
AddBOSvar(FMT_UINT8, (uint32_t)&var);

3) ReadRemote:
✅ ReadRemoteVar() – Reading a Remote BOS Variable

This function requests a variable from BOS Variable list in a neighbor module within the array.
ReadRemoteVar(srcModule, remoteVarAddress, &format, timeout);

Parameter Breakdown:

  • srcModule: ID of the module owning the BOS Variable.
  •  remoteVarAddress: BOS Variable index.
  • &format: Pointer to store the variable format.
  • timeout: Max wait time.

Example:

Module 1 requests a variable from the BOS Variable list in the destination module (Module 2).

// Module 1 code :
uint8_t var;
varFormat_t format;
var = *(uint8_t*)ReadRemoteVar(2, 1, &format, 0xFFFF);
// Module 2 code :
uint8_t var = 123;
AddBOSvar(FMT_UINT8, (uint32_t)&var);

✅✅ ReadRemoteMemory() – Reading from a Raw Remote Address
This function requests a value from a precise memory location in a neighbor module within
the array.

ReadRemoteMemory(srcModule, remoteMemoryAddress, format, timeout);

Parameter Breakdown:

  • srcModule: ID of the module to read from.
  • remoteMemoryAddress: Raw memory address.
  • format: Expected data format.
  • timeout: Maximum wait time.

Example:
Module 1 retrieves a value from a specific memory location in the destination module (Module 2).

// Module 1 (Reader)
uint8_t var;
var = *(uint8_t*)ReadRemoteMemory(2, 0x2000001C, FMT_UINT8, 0xFFFF);

✨ Tips and Notes ✨

  • Always declare variables as `volatile` when accessed remotely.
  • Use `AddBOSvar()` exclusively for BOS Variable index registration.
  • Direct memory access requires precise address knowledge and proper memory alignment. ️
  • Timeout ⏳ value 0xFFFF blocks indefinitely until operation completion. 
  • BOS Variable formats must match identically on both modules.

 

How can we help?