From 98fb96f16449ec33ba163ff3ec4f573537007c86 Mon Sep 17 00:00:00 2001 From: Giannis Kepas Date: Thu, 20 Mar 2025 09:26:21 +0200 Subject: [PATCH] update readme --- README.md | 38 +++++++++++++++----- http-bridge/README.md | 80 ++----------------------------------------- 2 files changed, 31 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 8669905..428dfa6 100644 --- a/README.md +++ b/README.md @@ -112,20 +112,40 @@ Move into the `http-bridge` folder and execute the following: ### NGSI-LD Entity Types -| Entity Type | Description | -| ------------------- | ---------------------------------------------------------- | -| ``WeatherObserved`` | Real-time weather conditions (temperature, humidity, etc.) | - -Additional entity types can be added dynamically by extending the Type Mapping Configuration. +| Entity Type | Description | +| --------------------- | ------------------------------------------------------------------------ | +| ``DeviceMeasurement`` | Device measurements which include records of all the sensors registered. | To support more NGSI-LD models: -1. Add a new type mapping in ``typeMaps/`` +1. Add a new type mapping in ``typeMaps/``. See the DeviceMeasurement typemap for the base structure. 2. Extend NGSITranslator.js to handle the new entity type 3. Modify generalControllers.js to process the new queries -## Testing +## Queries & Testing + +You can view the structure of HTTP queries and test the broker/bridge by using the following Postman workspace: + +**https://www.postman.com/retr0dev/workspace/uowm-depe-http-bridge** + +Clone the workspace into your own account and modify it to your needs. + +**Setting up Postman** -In order to test the broker and the http bridge you can use the sample queries provided at the following Postman workspace: +1. Setup the env variables. + - `broker-ip` : localhost if running locally otherwise the IP of your Scorpio broker + - `broker-port` : the port of the Scorpio broker + - `http-bridge-ip` : the IP address of the bridge - **CANNOT BE LOCALHOST** - If you are running the bridge on the same machine as your broker then you need to set the bridge IP to the machine IP. + - `http-bridge-port` : the port of the HTTP bridge +2. Register Context Source + - In the `Scorpio-Registration` POST request you need to add any new entity types you have implemented. +3. Test the broker + - If everything was setup correctly, you can use any of the GET requests to fetch data according to the request you selected. + The format the requests are following (where 'XYZ' is the entity type to fetch ) is: + - XYZ-Realtime : Latest data from the specific type. + - XYZ-Realtime-Attrs : Latest data from the specific type and the specific attribute listed in the params. + - XYZ-Temporal : Data from a specific date range. + - XYZ-Temporal-Attrs : Data from a specific date range and a specific attribute listed in the params. -**https://www.postman.com/payload-geoscientist-32828968/scorpio-broker-registration/overview** +*Note:* +The reason all Realtime requests have a limit on the database entries it will return is because we cannot fetch millions of records from a single query. The server cannot handle that. diff --git a/http-bridge/README.md b/http-bridge/README.md index 12ce0fa..686c3c6 100644 --- a/http-bridge/README.md +++ b/http-bridge/README.md @@ -2,84 +2,8 @@ ## **Overview** -The **HTTP Bridge** serves as a middleware between the **Scorpio Broker** and the **Smart City Heraklion API**. It is responsible for **fetching data from the API**, **translating it into the NGSI-LD format**, and **returning a structured response** that conforms to the **NGSI-LD data model**. +The **HTTP Bridge** serves as a middleware between the **Scorpio Broker** and a **API**. It is responsible for **fetching data from the API**, **translating it into the NGSI-LD format**, and **returning a structured response** that conforms to the **NGSI-LD data model**. --- -## **Getting Started** - -### **1. Prerequisites** -Ensure you have the following installed: -- **Docker** -- **Node.js** (v14 or higher, if running locally) -- **npm** (Node Package Manager) ---- - -### **2. Configuration** -Before running the application, configure the necessary environment variables. - -### **Using `.env` File (Recommended)** -Create a `.env` file in the project root with the following content: - -``` -PORT=9010 # Http Bridge Port -HOST="0.0.0.0" # Http Bridge Host (DONT CHANGE id running with Docker) -API_URL=https://smartcity.heraklion.gr/open-data-api # Base URL of the API -``` - -### **3. Running the HTTP Bridge** -1. Install npm packages -``` -npm install -``` - -2. Build the Docker Image -``` -docker build -t http-bridge . -``` - -3. Run the Container - -``` -docker run -d --name http-bridge -p 8080:8080 --env-file .env http-bridge -``` - -The bridge will be accessible at: **{HOST}:{PORT}** - -Default: **http://localhost:8080** - ---- -### **4. Stopping & Removing the Container** - -1. To stop the running container: -``` -docker stop http-bridge -``` - -2. To remove the container: -``` -docker rm http-bridge -``` - ---- - -## **Supported NGSI-LD Entity Types** -| **Entity Type** | **Description** | -|----------------------|--------------------------------------------------------| -| `WeatherObserved` | Real-time weather conditions (temperature, humidity, etc.) | - -Additional entity types can be added dynamically by extending the **Type Mapping Configuration**. - ---- - -## **Extending the Bridge** -To support more NGSI-LD models, simply: -1. **Add a new type mapping** in `typeMaps/` -2. **Extend `NGSITranslator.js`** to handle the new entity type -3. **Modify `generalControllers.js`** to process the new queries - ---- - -## **Extra Links** -[Scorpio Broker](https://github.com/efntallaris/scorpioBroker) -[Postman Workplace](https://www.postman.com/payload-geoscientist-32828968/workspace/scorpio-broker-registration) \ No newline at end of file +**See the README on the root of this repository for instructions on how to install and setup.** -- GitLab