Low Temperature Control

Capstone Project for Computer Engineering, Chulalongkorn University

Folder Structure

Apps

• heater-api (Heater API): API Server that controls heaters with PID (Python FastAPI; MOCK, GPIO, or PSU modes via config)
• ls-api (Lakeshore API): Lakeshore Management API (Python FastAPI app connecting USB Serial to Lakeshore Devices)
• rice-shower (Rice Shower): Data Collector for ls-api and heater-api. It also serves as a TSDB query server for the dashboard app. (Bun + Elysia)
• simulator (Environment Simulator): Simulator for Foam Box, works as stub/mocks for ls-api and heater-api (Bun + Elysia)
• web (Web Dashboard): Dashboard Application (Next.js)

Packages (Internal)

• api-client: API Client for each API service using openapi-generator and openapi-typescript
• config: ESLint and TypeScript configurations
• tsdb: Database Schema for TimescaleDB

• ui: React UI Component Library powered by Shadcn UI

.env

.env.dev and .env.lab are located in the folder of each apps/packages, most of them are already setup for local development, for lab mode you may need to change some values (like IP addresses).

When you edit IP Addresses for lab mode, please do not commit the changes.

Setup

This repository has two languages and three runtimes: TypeScript (Node.js and Bun) and Python.

Node.js and pnpm (Package Manager)

Use node.js with the version specified in .nvmrc file (currently lts/krypton or 24 LTS). Running node -v should output v24.x.x.

Recommend using nvm (Node Version Manager) to manage Node.js versions. Install nvm from nvm-sh/nvm.

Run corepack enable to enable Corepack, then run pnpm -v to verify that the version of pnpm matches the version specified in package.json.

Bun

Install Bun from bun.com.

Note that pnpm is still used as the package manager for Bun projects. You can run pnpm dev which will delegate to Bun.

Python + UV

Install Python with version specified in .python-version file (currently 3.13) and use uv (Python package/project manager). Install uv and run uv sync at the repository root to install dependencies.

Docker

Make sure you have Docker Desktop or Orbstack installed.

These are the container you will be running for local developments:

• timescaledb: TimescaleDB (A time-series database built on PostgreSQL)
• (Optional) grafana: Grafana (For testing SQL queries locally)
• tempo, prometheus, otel-collector: tracing/metrics stack (OTLP ports 4317/4318)

You can run these containers using docker-compose.yaml file provided in the root of this repository:

docker compose up -d

Database Setup

Go to packages/tsdb, .env should already be setup for local development.

Then run pnpm --filter @repo/tsdb db:migrate to setup the database schema.

Architecture Diagram

Running Locally

Use command pnpm run dev to run all services with mock devices that connects to the simulator. .env.dev is already set and should not require any changes.

Running in Lab Mode

Lab Mode is when you are using the real devices (Lakeshore 240 and Heater)

To run Lab Mode, make sure you filled in neccessary IPs in .env.lab files in each apps that requires it.

Then run pnpm run lab to start the services in Lab Mode as Configuration A (run all services on one device).

To use GPIO mode on Raspberry Pi, add RPi.GPIO to the heater-api project, e.g. from the repo root: uv add --package heater-api RPi.GPIO

URLs

• Lakeshore API (ls-api) Swagger will be available at http://localhost:8000/docs or alternate scalar UI at http://localhost:8000/scalar
• Heater API Swagger will be available at http://localhost:8001/docs or alternate scalar UI at http://localhost:8001/scalar
• Rice Shower API Docs will be available at http://localhost:8100/openapi
• Simulator API Docs will be available at http://localhost:8101/openapi
• Web Dashboard will be available at http://localhost:3100

Contribution

OpenAPI and Codegen

When making changes to the API servers (ls-api, heater-api, rice-shower, or simulator), the OpenAPI files under docs/** for that project are updated when that server starts (per app implementation).

However, you still have to run pnpm codegen in the root of the repository to regenerate the API Client packages used in other projects.

Please make sure to do this step before creating a pull request.