Air Tracking

Atmospheric monitoring system dashboard

View Demo · Documentation · Report Bug · Request Feature

📔 Table of Contents

• About the Project
  • Screenshots
  • Tech Stack
  • Features
  • Environment Variables
• Getting Started
  • Prerequisites
  • Run Locally
  • Deployment
• Usage
  • Access Node-RED editor
  • Import flow
  • Node-RED dashboard first setups
  • Deploy flow
  • Value range
  • MQTT JSON Schema
  • Connect IFTTT
• Roadmap
• Contributing
  • Code of Conduct
• FAQ
• License
• Contact
• Acknowledgements

🌟 About the Project

📷 Screenshots

👾 Tech Stack

Client

• Javascript
• Node-RED

Server

• Express.js

🎯 Features

• Show average measured data:
  • Dust density.
  • Air quality.
  • Temperature.
  • Humidity.
• Show the data chart for a specific date.
• Locate all devices.
• Show and turn on/off device status.
• Send device danger warning to mobile.

🔑 Environment Variables

To run this project, you will need to add the following environment variables to your .env file:

• Node-RED configs:

  NODERED_USERNAME: Username to log in to Node-RED editor.

  NODERED_PASSWORD: Password to login to Node-RED editor.

• ThingSpeak configs:

  THINGSPEAK_CHANNEL_ID: ThingSpeak channel ID to read data from.

  THINGSPEAK_WRITE_KEY: ThingSpeak write key to write data to.

  THINGSPEAK_READ_KEY: ThingSpeak read key to read data from.

• IFTTT configs:

  IFTTT_URL: IFFTT URL to send a notification to.

E.g:

# .env
NODERED_USERNAME=admin
NODERED_PASSWORD=password

THINGSPEAK_CHANNEL_ID=1461192
THINGSPEAK_WRITE_KEY=RRFDXXCAA6DSDP84
THINGSPEAK_READ_KEY=V348J6XADWL2NUB60

IFTTT_URL=https://maker.ifttt.com/trigger/{event}/with/key/crMzTDLXl...

Note: NODERED_USERNAME and NODERED_PASSWORD is used for admin user. You can add other users in the file bin/www.

Read more about customizing users and other ways to generate passwords: Securing Node-RED.

Note: You change tweak Node-RED settings in file bin/www.

You can also check out the file .env.example to see all required environment variables.

🧰 Getting Started

‼️ Prerequisites

• A MQTT broker service.

• This project uses Yarn as package manager:

  npm install --global yarn

🏃 Run Locally

Clone the project:

git clone https://github.com/DuckyMomo20012/air-tracking.git

Go to the project directory:

cd air-tracking

Install dependencies:

yarn

Start the server:

yarn start

OR:

Run with nodemon:

yarn test

---

Access server:

The server will run on: http://localhost:3000/red/

🚩 Deployment

To deploy this project on Heroku:

👀 Usage

⚙️ Customize Node-RED

• You can custom your Node-RED configuration in file bin/www.

  • httpAdminRoot: the root URL for the editor UI. If set to false, all admin endpoints are disabled. This includes both API endpoints and the editor UI. To disable just the editor UI, see the disableEditor property below. Default: /.

  • httpNodeRoot: the root URL for nodes that provide HTTP endpoints. If set to false, all node-based HTTP endpoints are disabled. Default: /.

  • userDir: the directory to store all user data, such as flow and credential files and all library data. Default: $HOME/.node-red.

  • flowFile: the file used to store the flows. Default: flows_<hostname>.json.

  • functionGlobalContext: Function Nodes - a collection of objects to attach to the global function context. For example,

    functionGlobalContext: {
      osModule: require('os');
    }

    can be accessed in a function node as:

    var myos = global.get('osModule');

  • adminAuth: enables user-level security in the editor and admin API. See Securing Node-RED for more information.

• This project configure these settings:

  // bin/www
  const settings = {
    httpAdminRoot: '/red',
    httpNodeRoot: '/air-tracking',
    userDir: './.node-red/',
    flowFile: 'flows.json',
    functionGlobalContext: {
      THINGSPEAK_CHANNEL_ID: process.env.THINGSPEAK_CHANNEL_ID,
      THINGSPEAK_WRITE_KEY: process.env.THINGSPEAK_WRITE_KEY,
      THINGSPEAK_READ_KEY: process.env.THINGSPEAK_READ_KEY,
      IFTTT_URL: process.env.IFTTT_URL,
    }, // enables global context
    adminAuth: {
      type: 'credentials',
      users: [
        // This is admin user credentials
        {
          username: process.env.NODERED_USERNAME,
          password: bcryptjs.hashSync(process.env.NODERED_PASSWORD, 8),
          permissions: '*',
        },
      ],
    },
  };

Note: Read more about Node-RED configuration: Runtime Configuration.

⏩ Access Node-RED editor

• Go to http://localhost:3000/red/ to view the Node-RED editor.

• Go to http://localhost:3000/air-tracking/ui/ to view web UI (from node-red-dashboard node).

• Go to http://localhost:3000/air-tracking/worldmap/ to view world map (from node-red-contrib-web-worldmap node).

Note: Remember to deploy your flow before accessing node routes.

📥 Import flow

• Go to the hamburger button on the top right of the editor.
• Click the Import button.
• Then import file flows.json from folder data.

1️⃣ Node-RED dashboard first setups

• In Node-RED editor go to each MQTT node to edit server URL, topics...

• Change the web title in the dashboard/site tab (on the right-side panel).

• Change the web main color theme in the dashboard/theme tab.

• If you don't have MQTT, you can connect node MQTT emulator (in Node-RED editor) to inject sample data:

  

  OR:

  You can use MQTT explorer to inject a sample MQTT data:

  

  Example image from MQTT explorer website

🚀 Deploy flow

• Click the Deploy button in the Node-RED editor to deploy flow.
• After deploying, your flow will be saved in the .node-red folder.

Note: File flow.json in the .node-red folder will be loaded for the next server run. So you can push this .node-red folder to your repo to save your work, instead of importing the file flow.json manually.

🔢 Value range

• Humidity(%):

  • 0 - 20: Uncomfortably dry.
  • 20 - 60: Normal.
  • 60 - 100: Uncomfortably wet.

• Temperature(℃):

  • 0 - 20: Temperature is too cold.
  • 20 - 35: Normal.
  • 35 - 50: Temperature is too hot.

• Dust density (mg/m3):

  • 0 - 3: Normal
  • 3 - 10: Normal
  • 10 - 50: Dust density is too high.

• Air quality:

  • 0 - 190: Normal.
  • 190 - 300: Normal.
  • 300 - 500: Air quality is too poor.

📝 MQTT JSON Schema:

Your MQTT broker service should send data with this schema:

JSON Schema

{
  "type": "object",
  "required": [],
  "properties": {
    "devices": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [],
        "properties": {
          "id": {
            "type": "string"
          },
          "air_quality": {
            "type": "number"
          },
          "dust_density": {
            "type": "number"
          },
          "humidity": {
            "type": "number"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "temperature": {
            "type": "number"
          },
          "working": {
            "type": "boolean"
          }
        }
      }
    }
  }
}

Note: You can see sample MQTT data in folder data. File dangerous-data.json and normal-data.json.

🔌 Connect IFTTT

Follow this tutorial to create an IFTTT applet and test.

Webhook service configuration

Notification service configuration

Note: Value1 is required.

🧭 Roadmap

• Update dashboard UI.

✨ Contributors

Thanks goes to these wonderful people (emoji key):

Dương Tiến Vinh 💻 📖

Le Nguyen Tu Van 🎨 📹 📖

Qhope 💻 🎨 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

📜 Code of Conduct

Please read the Code of Conduct.

❔ FAQ

• Is this project still maintained?

  • Yes, but we will only update UI, docs, or dependencies. New features won't be added frequently.

• Can I add Express routes to this project?

  • Yes, you can. This project is adoption from Node-RED official example to embed Node-RED to Express application.

    Read more: Embedding into an existing app

• How can I configure my Node-RED application?

  • Go to file bin/www, then configure settings variable.

    Read more: Configuration

⚠️ License

Distributed under MIT license. See LICENSE for more information.

🤝 Contact

Duong Vinh - @duckymomo20012 - tienvinh.duong4@gmail.com

Project Link: https://github.com/DuckyMomo20012/air-tracking.

💎 Acknowledgements

Here are useful resources and libraries that we have used in our projects:

• Node-RED: A powerful tool to build IoT applications.
• Awesome Readme Template: A detailed template to bootstrap your README file quickly.