ColdGuard TRY IT OUT Tutorial

This is a tutorial on how to try out ColdGuard for yourself. The tutorial does not host ColdGuard itself, except for the MCP server, which is hosted at 43.110.38.178:8080/mcp. That server is set to expire in about 25 days (as of 7/6/2025) and is guarded by the usual SSH keys, but accessing the MCP server is free and should work for you.

Otherwise, you'll need to host it yourself or run it locally. More details about using the MCP are given in the Backend section.

Get your materials. You'll need an ESP32 — any model will do, but this was tested with a dev module (WROOM-32).

• A red LED, green LED, buzzer, DC motor fan, and a DHT11/DHT22 sensor (DHT11 is recommended).

How you connect the hardware is up to you, since you can just change the pin modes in the app and in the code. Ideally, here is the default connection approach:

Connect the ESP32 to your PC using a USB cable, open your IDE (VS Code, for example), and install PlatformIO via the VS Code extension tab.

Now clone this codebase:

git clone https://github.com/pius-code/coldGuardEdge

After cloning, open the folder and navigate to the src folder, then follow these steps:

1. Create a config file (src/config.h). This file will store your environment variables for security purposes.

2. Paste and fill out the following:

   #define SENSOR_API_URL "http://<vps-ip>:<port>/api/v1/sensor/add_data"
   #define ASHA_REGISTER_URL "http://<vps-ip>:<port>/api/v1/asha/verify_and_register_device"
   #define WIFI_SSID "your-wifi-name"
   #define WIFI_PASSWORD "your-wifi-password"
   #define MQTT_BROKER "192.168.x.x" // IP of your MQTT broker
   #define MQTT_PORT 1883
   #define ASHA_ID "your-device-uuid"

   For simplicity in testing, just use the VPS IP 43.110.38.178, or swap in your own IP if you have one.

3. Open main.cpp in src/main.cpp.

4. Set your Wi-Fi SSID and password — needed to sync sensor data to the cloud when internet is available and to register devices.

5. Connect your ESP32 via USB and click upload.

For more help, see the README here: https://github.com/pius-code/coldGuardEdge

The mobile app is tested with Android and was built with Flutter.

• Download it from here: https://github.com/pius-code/coldguard/releases/tag/v1.0.0
• Or find the source here: https://github.com/pius-code/coldguard

The codebase contains instructions on how to build for your platform (iOS/Web/Linux/Android, etc).

Using the app is pretty intuitive:

1. Open the app.
2. Input the MQTT broker IP (it should be the same as that of the ESP32). Self-host an MQTT server on your phone (search "MQTT" on the Play Store) — this ensures a true offline solution.
3. Select and load your Qwen model. Go to Hugging Face and search for Qwen3-0.6B.litertlm, Qwen2.5-1.5-Instruct_multi-prefill-seq_q8_ekv4096.litertlm, or any supported LiteRT-LM Qwen model.
4. Start querying the agent, for example:
   • "Turn on the red light"
   • "Turn off the fan"
   • "What's the temperature of the unit?"
   • "Turn on the green light if the humidity exceeds 80"
   • "Turn on the fan if the temperature of the unit gets above 25°C"

You can edit the prompt by clicking the settings icon in the app to suit your preference or style. Feel free to change the pin numbers of the sensors or actuators in the app to match your ESP32.

1. Clone this repo: https://github.com/pius-code/coldGuardFrontend

   This is the WhatsApp interface. It is not hosted, since it relies on an unofficial WhatsApp server, and for a hackathon you probably don't need to go through the hurdle of registering a WhatsApp Business account.

2. Create a .env file in the root and place this info there:

   REDIS_URL=redis://red-xxxxxxxxxxxxxx
   REDIS_URL_LOCAL=redis://localhost:6379
   MCP_URL=http://<your-server-url>:8080/mcp
   QWEN_API_KEY="your qwen api key"
   ALLOWED_NUMBER="your allowed number"
   

   • You can skip REDIS_URL if you don't have a hosted Redis instance.
   • For MCP_URL, use http://43.110.38.178:8080/mcp for simplicity, or jump to the Backend section to understand how to run and host your own.
   • Fill in your Qwen API key by getting it from the Qwen Model Studio dashboard.

   NB: For ALLOWED_NUMBER, if you don't know your WhatsApp ID, do this instead:

   After cloning the codebase, run npm install followed by npm run dev. If everything goes smoothly, you should see a QR code in the terminal. Open the WhatsApp account you want the AI to operate in (ideally your second WhatsApp), tap the three dots at the top, tap "Linked devices," then "Link a device." This lets you scan the QR code and pair. Now send a message to that number — the sender ID (you, in this case) should print in the terminal. Copy that and paste it into the .env file, replacing "your allowed number".

Everything after that should work. The frontend handles the agent automatically — it connects to the MCP, handles failures, tool calls, scheduling, context management, and overall agent orchestration.

• Click prompts/sys_pro.ts and edit the system prompt to suit your desired structure, etc.
• To change models, edit model.ts and add or edit your preferred model. The default is Qwen3-0.6B, chosen for its speed and long context. If you change the model here, open handler/groq.ts, import the new model, and make the changes across the relevant lines (47 and 93, at time of writing, wherever you see qwen_35).

It should work without touching any of that out of the box.

Queries you can try:

• "What can you do?"
• "Prepare me a report every Friday at 5pm."
• "What's the state of the drugs?"
• "Are the vaccines healthy?"
• "What do these results mean?"

Or general conversation — it's an LLM after all. The README in the app repo contains all the details you'd need.

The backend is hosted at 43.110.38.178:8080/mcp.

For your own testing, you can host it yourself. The backend is a simple FastAPI app that handles the MCP (Model Context Protocol) for the ColdGuard system.

1. Clone the repo: https://github.com/pius-code/coldGuardBackend
2. The first thing you should do is read the README.md in the repo.
3. The rest should work out of the box.

For now, adding sensor data is unguarded at the route level, but in future it will be gated by device (ESP32) ID.

Tools in the MCP:

1. Get sensor data — Allows the agent to fetch data from the ESP32 and use it to make decisions. The agent can call this tool to get the latest sensor readings.
2. build_vaccine_report — Allows the agent to perform extensive research, following guidelines and sequential steps, to build a report. The frontend renders the report as a PDF and passes the context into the conversation.

For a production-level setup you'd need to add OAuth, but it's skipped in this tutorial for simplicity. You can add it yourself if you want to host your own MCP server.

Hosting the MCP is as simple as hosting any other FastAPI app:

1. Rent an Alibaba ECS instance, preferably running Alibaba Linux.
2. Install Python and pip/uv.
3. Clone the repo and use PM2 to run the app in the background.
4. Open port 8080 in your firewall and security group settings.
5. You can now access the MCP server at http://<your-ecs-ip>:8080/mcp.

Raise an issue if you need help hosting your own MCP server, and I'll help you out.