🎉 V-Portal 0.5.2 is released! Read more
Skip to Content
Developer & Integrator GuideModule DevelopmentOverview

Module Development

Learn how to create custom modules to extend V-Portal’s functionality.

What is a Module?

A V-Portal module is a package containing:

  • Backend Component (C++): Business logic, hardware integration
  • Frontend Component (JavaScript/Vue): User interface
  • Module Descriptor (module.json): Metadata and configuration

Module Structure

    • module.json
      • CMakeLists.txt
      • package.json
        • main.js
        • module.ts

Backend Module

Module Interface

Implement ModuleInterface:

#include "sdk/module_interface.h"
 
class MyModule : public ModuleInterface {
public:
    std::string name() const override {
        return "My Module";
    }
    
    std::string version() const override {
        return "1.0.0";
    }
    
    void initialize() override {
        // Setup code
        registerRoutes();
        setupDataFields();
    }
    
    void cleanup() override {
        // Cleanup code
    }
};
 
EXPORT_MODULE(MyModule)

Registering Routes

void MyModule::registerRoutes() {
    auto& registry = ServiceRegistry::instance()
        .getService<RouteRegistry>();
        
    registry.registerRoute(
        "/api/mymodule/status",
        [this](const crow::request& req) {
            return crow::response(200, "OK");
        }
    );
}

Data Fields

void MyModule::setupDataFields() {
    auto& df = ServiceRegistry::instance()
        .getService<DataFieldService>();
        
    // Publish data
    df.publish("mymodule.status", "running");
    
    // Subscribe to data
    df.subscribe("robot.position", [](const auto& value) {
        // Handle updates
    });
}

Frontend Module

Module Registration

// module.ts
import { ModuleBase } from 'sdk/modules/moduleBase'
 
export class MyModule extends ModuleBase {
  name = 'My Module'
  version = '1.0.0'
  
  async initialize() {
    this.registerWidgets()
    this.registerPages()
  }
}
 
export default new MyModule()

Custom Widgets

import { WidgetBase } from 'sdk/widgets/widgetBase'
 
export class MyWidget extends WidgetBase {
  name = 'My Widget'
  
  render() {
    // Vue component
    return {
      template: '<div>{{ status }}</div>',
      data() {
        return { status: 'Ready' }
      }
    }
  }
}

Module Descriptor

module.json:

{
  "name": "my-module",
  "displayName": "My Module",
  "version": "1.0.0",
  "description": "Custom module for V-Portal",
  "author": "Your Name",
  "backend": {
    "entry": "libmymodule.so"
  },
  "frontend": {
    "entry": "dist/main.js"
  },
  "dependencies": {
    "core": ">=0.5.0"
  }
}

Building Modules

Backend Build

cd backend
mkdir build && cd build
cmake ..
make

Frontend Build

cd frontend
npm install
npm run build

Package Module

# Creates my-module.vmod
./scripts/package-module.sh my-module

Testing Modules

  1. Build the module
  2. Install in V-Portal: Upload .vmod file
  3. Enable the module
  4. Test functionality
  5. Check logs for errors

Best Practices

  • Version Control: Use semantic versioning
  • Error Handling: Always handle errors gracefully
  • Logging: Use V-Portal’s logging system
  • Documentation: Document all public APIs
  • Testing: Write unit tests for backend code

Next Steps

Last updated on
OverviewFrontend Setup Guide