Asoba Ona Documentation
Home Insights Contact Us

Control Layer

The Control Layer aggregates predictions from all active nodes, executes Decision AI routines for task scheduling and coordination, and provides secure APIs for integration with maintenance management systems.

Overview

The Control Layer serves as the central coordination hub for the Ona Platform. It aggregates predictions from all edge nodes, executes Decision AI routines for task scheduling and coordination, maintains a unified dashboard for operators, and provides secure APIs for integration with maintenance management systems such as SAP PM or Maximo.

Key Capabilities:

API Gateway

Base URLs

The Ona Platform exposes a RESTful API through AWS API Gateway:

API Gateway Configuration

Status: ✅ ACTIVE

Features

Terminal API Endpoints (OODA Workflow)

The Control Layer provides comprehensive Terminal API endpoints that implement the OODA (Observe-Orient-Decide-Act) workflow for operations and maintenance.

POST /terminal/assets

Manage solar assets and components.

Purpose: Create, list, and retrieve asset information

Authentication: API key or IAM role

Content-Type: application/json

Actions:

Example Request (add):

{
  "action": "add",
  "asset_id": "INV-001",
  "name": "Main Inverter 1",
  "type": "Solar Inverter",
  "capacity_kw": 20.0,
  "location": "Cape Town Solar Farm",
  "components": [
    {
      "oem": "Sungrow",
      "model": "SG20KTL",
      "serial": "SN123456"
    }
  ]
}

Example Response:

{
  "message": "Asset created successfully",
  "asset_id": "INV-001"
}

POST /terminal/detect

Run fault detection on assets.

Purpose: Execute anomaly detection and fault identification

Authentication: API key or IAM role

Actions:

Example Request:

{
  "action": "run",
  "asset_id": "INV-001"
}

Example Response:

{
  "message": "Detection completed",
  "asset_id": "INV-001",
  "detections": []
}

POST /terminal/diagnose

Run AI diagnostics on detected faults.

Purpose: Classify faults and provide root cause analysis

Authentication: API key or IAM role

Actions:

Example Request:

{
  "action": "run",
  "asset_id": "INV-001"
}

Example Response:

{
  "message": "Diagnostics completed",
  "asset_id": "INV-001",
  "diagnostics": []
}

POST /terminal/schedule

Create maintenance schedules.

Purpose: Schedule maintenance activities and optimize resource allocation

Authentication: API key or IAM role

Actions:

Example Response:

{
  "message": "Schedule created",
  "schedule_id": "sched-uuid"
}

POST /terminal/bom

Build bill of materials for maintenance.

Purpose: Generate parts lists and cost estimates for maintenance jobs

Authentication: API key or IAM role

Actions:

Example Response:

{
  "message": "BOM built",
  "bom_id": "bom-uuid"
}

POST /terminal/order

Create work orders.

Purpose: Generate work orders for maintenance execution

Authentication: API key or IAM role

Actions:

Example Response:

{
  "message": "Order created",
  "order_id": "ord-uuid"
}

POST /terminal/track

Track job status and progress.

Purpose: Monitor work order execution and job progress

Authentication: API key or IAM role

Actions:

Example Response:

{
  "message": "Tracking subscription created",
  "job_id": "job-uuid"
}

Authentication and Security

API Key Authentication

Include your API key in the request header:

curl -H "X-API-Key: your-api-key" \
     -X POST https://api.asoba.co/terminal/assets

Or as a query parameter:

curl "https://api.asoba.co/forecast?customer_id=test&api_key=your-api-key"

IAM Role Authentication

Use AWS credentials for authentication:

# Configure AWS credentials
aws configure

# Use AWS signature in requests
curl -H "Authorization: AWS4-HMAC-SHA256 ..." \
     -X POST https://api.asoba.co/terminal/assets

Security Headers

Request/Response Formats

Standard Response Format

All successful API responses follow this structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2025-01-15T12:00:00Z",
    "version": "v1.0"
  },
  "errors": []
}

Error Response Format

Error responses follow this structure:

{
  "success": false,
  "data": null,
  "metadata": {
    "request_id": "uuid",
    "timestamp": "2025-01-15T12:00:00Z",
    "version": "v1.0"
  },
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Invalid customer_id format",
      "field": "customer_id",
      "details": "Expected format: alphanumeric string"
    }
  ]
}

Rate Limiting and Quotas

Rate Limits by Tier

Tier Requests/Hour Burst Limit
Standard 1,000 100
Premium 10,000 1,000
Enterprise 100,000 10,000

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 755
X-RateLimit-Reset: 1642248000

Quota Exceeded Response

When rate limit is exceeded:

{
  "success": false,
  "data": null,
  "errors": [
    {
      "code": "QUOTA_EXCEEDED",
      "message": "Rate limit exceeded. Try again later.",
      "retry_after": 3600
    }
  ]
}

HTTP Status: 429 Too Many Requests

Task Scheduling and Coordination

Decision AI Routines

The Control Layer executes Decision AI routines that:

Unified Dashboard

The Control Layer maintains a unified dashboard for operators that provides:

CMMS Integration

Supported Systems

The Control Layer provides secure APIs for integration with maintenance management systems:

Integration Features

API Integration Example

# Create work order via API
curl -X POST https://api.asoba.co/terminal/order \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "asset_id": "INV-001",
    "priority": "high",
    "description": "Inverter fault detected"
  }'

Lambda Services

The Control Layer is powered by the Terminal API Lambda function:

Terminal API Service

ona-terminalApi-prod

Data Management

DynamoDB Tables

The Control Layer uses DynamoDB tables for data storage:

Terminal Tables:

Platform Tables:

S3 Storage

Input Bucket: sa-api-client-input

Output Bucket: sa-api-client-output

Monitoring and Observability

CloudWatch Integration

Performance Metrics

Next Steps

Get Help & Stay Updated

Contact Support

For technical assistance, feature requests, or any other questions, please reach out to our dedicated support team.

Email Support Join Our Discord

Subscribe to Updates

* indicates required