Getting Started

Getting Started

This guide will help you set up and start using the Roboscope 2 platform.

Prerequisites

For API Development

• PostgreSQL 14 or later
• Redis 7 or later
• Rust 1.70+ (for API server)
• Git

For iOS Development

• macOS 13+ (Ventura or later)
• Xcode 15+
• iOS Device with LiDAR (iPhone 12 Pro+, iPad Pro 2020+)
• iOS 17+
• Swift 5.9+

Quick Start (API)

1. Clone the Repository

git clone https://github.com/your-org/roboscope_2.git
cd roboscope_2/roboscope_2_api

2. Set Up Database

# Install PostgreSQL (macOS)
brew install postgresql@14
brew services start postgresql@14

# Create database
createdb roboscope_dev

# Install PostGIS extension
psql roboscope_dev -c "CREATE EXTENSION IF NOT EXISTS postgis;"

3. Set Up Redis

# Install Redis (macOS)
brew install redis
brew services start redis

4. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env with your settings
DATABASE_URL=postgresql://localhost/roboscope_dev
REDIS_URL=redis://localhost:6379
PORT=8080
RUST_LOG=info

5. Run Migrations

# Install sqlx-cli
cargo install sqlx-cli --no-default-features --features postgres

# Run migrations
sqlx migrate run

6. Start the Server

# Development mode (with auto-reload)
cargo watch -x run

# Or standard run
cargo run

The API will be available at http://localhost:8080

7. Verify Installation

# Health check
curl http://localhost:8080/health

# Expected response:
# {"status":"healthy","database":"connected","redis":"connected"}

8. Seed Test Data (Optional)

./scripts/seed-dev.sh

Quick Start (iOS)

1. Open Xcode Project

cd roboscope_2/roboscope_2_ios
open roboscope2.xcodeproj

2. Install Dependencies

The project uses Swift Package Manager. Dependencies should resolve automatically in Xcode.

If needed, manually resolve:

File → Packages → Resolve Package Versions

3. Configure API Endpoint

Edit roboscope2/Services/Network/APIConfiguration.swift:

struct APIConfiguration {
    static var shared = APIConfiguration()

    // Change to your API server URL
    var baseURL: String {
        switch environment {
        case .development:
            return "http://localhost:8080/api/v1"  // Local dev
        case .production:
            return "https://api.roboscope.example.com/api/v1"
        }
    }

    var environment: Environment = .development
}

4. Configure Signing

1. Select the project in Xcode navigator
2. Select roboscope2 target
3. Go to Signing & Capabilities
4. Select your Team
5. Xcode will automatically manage provisioning

5. Build and Run

1. Connect your LiDAR-enabled iOS device
2. Select device in Xcode
3. Press Cmd+R to build and run

6. Grant Permissions

On first launch, grant:

• Camera access (required for AR)
• Local Network access (required for API communication)

Your First Work Session

1. Create a Space

curl -X POST http://localhost:8080/api/v1/spaces \
  -H "Content-Type: application/json" \
  -d '{
    "key": "my-room",
    "name": "My First Room",
    "calibration_vector": [0, 0, 0]
  }'

Response will include the space id. Save it for next steps.

2. Create a Work Session

curl -X POST http://localhost:8080/api/v1/work-sessions \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "YOUR_SPACE_ID",
    "session_type": "inspection",
    "status": "active",
    "started_at": "2025-01-16T10:00:00Z"
  }'

Response will include the session id.

3. Create a Marker

curl -X POST http://localhost:8080/api/v1/markers \
  -H "Content-Type: application/json" \
  -d '{
    "work_session_id": "YOUR_SESSION_ID",
    "label": "Test Marker",
    "p1": [0.0, 0.0, 0.0],
    "p2": [0.1, 0.0, 0.0],
    "p3": [0.1, 0.1, 0.0],
    "p4": [0.0, 0.1, 0.0],
    "color": "#FF0000",
    "custom_props": {
      "severity": "medium",
      "type": "test"
    }
  }'

4. Calculate Marker Details

curl -X POST http://localhost:8080/api/v1/markers/YOUR_MARKER_ID/details/calculate

5. List All Markers

curl "http://localhost:8080/api/v1/markers?work_session_id=YOUR_SESSION_ID"

Using the iOS App

1. Create a Space

• Tap Spaces tab
• Tap + button
• Enter space name and details
• Tap Save

2. Start a Work Session

• Select your space
• Tap Sessions tab
• Tap New Session
• Choose session type
• Tap Start

3. Place Markers in AR

• In active session, tap AR View
• Point device at target surface
• Tap and drag to define marker corners
• Release to create marker
• Add label and properties

4. View Marker Details

• Tap on a marker in the list
• View calculated metrics:
  • Center location
  • Dimensions
  • Distances
• Edit custom properties

Portal (Web Interface)

1. Navigate to Portal

cd roboscope_2/roboscope_2_portal

2. Install Dependencies

npm install
# or
pnpm install

3. Configure API URL

Edit .env.local:

NEXT_PUBLIC_API_URL=http://localhost:8080/api/v1

4. Start Development Server

npm run dev
# or
pnpm dev

Open http://localhost:3000 in your browser.

5. Explore Features

• Browse spaces and sessions
• View markers with 3D visualization
• Export/import sessions
• Real-time presence tracking
• Marker analytics and reports

Common Tasks

Reset Database

# Drop all tables
sqlx database drop
sqlx database create
sqlx migrate run

View Logs

# API logs
cargo run  # Logs to stdout

# iOS logs
# In Xcode: View → Debug Area → Show Debug Area

Run Tests

# API tests
cargo test

# iOS tests (in Xcode)
# Product → Test (Cmd+U)

Clean Build

# API
cargo clean

# iOS (in Xcode)
# Product → Clean Build Folder (Cmd+Shift+K)

Development Workflow

1. Backend Development

# Watch mode (auto-reload on changes)
cargo watch -x run

# Run specific test
cargo test test_name

# Check code
cargo clippy

# Format code
cargo fmt

2. iOS Development

# Build
Cmd+B

# Run on device
Cmd+R

# Run tests
Cmd+U

# Clean build folder
Cmd+Shift+K

3. Database Changes

# Create new migration
sqlx migrate add migration_name

# Run migrations
sqlx migrate run

# Revert last migration
sqlx migrate revert

Troubleshooting

Database Connection Issues

# Check PostgreSQL is running
brew services list | grep postgresql

# Test connection
psql roboscope_dev -c "SELECT 1"

Redis Connection Issues

# Check Redis is running
brew services list | grep redis

# Test connection
redis-cli ping
# Expected: PONG

iOS Build Errors

1. Clean build folder: Cmd+Shift+K
2. Delete Derived Data: Xcode → Preferences → Locations → Derived Data → Delete
3. Reset Package Cache: File → Packages → Reset Package Caches

API Not Reachable from iOS

1. Check API is running: curl http://localhost:8080/health
2. Use correct IP address (not localhost) in iOS
3. Ensure both devices on same network
4. Check firewall settings

LiDAR Not Working

1. Verify device has LiDAR (iPhone 12 Pro+, iPad Pro 2020+)
2. Check camera permissions granted
3. Ensure good lighting
4. Update to latest iOS version

Next Steps

• Understand the Data Model
• Explore API Endpoints
• iOS Integration Guide
• Learn about Marker Details
• View Workflow Examples

Resources

• API Documentation
• GitHub Repository
• Issue Tracker

Support

For questions or issues:

• Open an issue on GitHub
• Check existing documentation
• Review code examples in /specs/examples/