Getting Started with sim-dashboard¶
This guide walks you through setting up and running the sim-dashboard application for local development.
Prerequisites¶
- Node.js 18+ (or equivalent runtime)
- npm or pnpm package manager
- Inklet backend running on
http://localhost:4000(required for authentication)
Installation¶
Clone the repository and install dependencies:
Or with pnpm:
Configuration¶
Create a .env file in the project root:
| Variable | Description |
|---|---|
VITE_AUTH_URL |
URL of the Inklet backend API. Used for authentication and device API calls. |
Note
The VITE_ prefix is required for Vite to expose the variable to the frontend. The Fastify server reads its configuration separately.
Running¶
Start both the Fastify server and the Vite dev server:
This starts:
- Fastify server on
http://localhost:3001--- receives framebuffers from sim-hw, WebSocket broadcast - React frontend on
http://localhost:5173--- user interface with e-ink display rendering
Using the Dashboard¶
Step 1: Open the Dashboard¶
Navigate to http://localhost:5173 in your browser.
Step 2: Log In¶
Click Sign In and authenticate with your Inklet account credentials. This is the same account you use with the portal or created via the Auth API.
No Account Yet?
Register a new account using the API:
curl -X POST http://localhost:4000/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "username": "yourname", "password": "password123"}'
Step 3: View Your Devices¶
After logging in, the dashboard displays all devices bound to your account. Each device card shows:
- Device name (Thing name)
- Online/offline status
- Battery level
- Last seen timestamp
- Live e-ink display preview
If you have no bound devices, the dashboard will be empty. See Device Binding to bind a simulated device.
Step 4: Start a Simulated Device¶
In a separate terminal, start a sim-hw instance:
The simulated device will:
- Connect to AWS IoT Core
- Send heartbeats to the backend
- Request a claim code (if unbound)
- Push framebuffers to
http://localhost:3001
Step 5: Bind and Interact¶
Once the device is running and bound to your account (see Device Binding), you will see its live e-ink display in the dashboard. Any commands sent to the device will update the display in real time.
Public Device View¶
Each device has a public URL that does not require authentication:
Replace {hwid} with the device's hardware UUID. This page shows:
- The device's current e-ink display content
- Live updates via WebSocket
- Device status information
Sharing
The public device URL is useful for demos, monitoring dashboards, or sharing a device's display with others who do not have an Inklet account.
Development¶
Project Structure¶
sim-dashboard/
├── server/ # Fastify server
│ ├── index.ts # Server entry point
│ ├── routes/ # HTTP routes (framebuffer, health)
│ └── ws/ # WebSocket handlers
├── src/ # React frontend
│ ├── components/ # UI components
│ ├── pages/ # Route pages
│ ├── hooks/ # React hooks
│ └── lib/ # Utilities and API client
├── .env # Environment configuration
├── package.json
└── vite.config.ts
Hot Reload¶
Both the Fastify server and React frontend support hot module replacement. Changes to source files are reflected immediately in the browser without a full page reload.
Troubleshooting¶
"Failed to fetch" on login¶
Ensure the Inklet backend is running on the URL specified in VITE_AUTH_URL:
Devices not showing framebuffers¶
- Verify sim-hw is running and configured with
--sim-url http://localhost:3001 - Check the Fastify server logs for incoming POST requests
- Verify the WebSocket connection in the browser dev tools (Network > WS tab)
Port conflicts¶
If ports 3001 or 5173 are already in use, check for other running processes: