Travail à réaliser

Structure du projet

Comme vu dans le tutoriel, le code que vous avez contient deux serveurs, un serveur HTTP qui écoute sur le port 8080 et un serveur UDP qui écoute sur le port 12345.

Le serveur HTTP va nous servir à collecter les informations envoyées par un capteur simulé et à répondre aux demandes du frontend. Le serveur UDP lui ne servira qu’à collecter les information d’un second type de capteur simulé.

Vous pouvez lancer le projet avec docker en utilisant le fichier docker-compose.yml fourni dans l’archive. Celui-ci contient les définitions des services à lancer (pour cette activité, deux capteurs simulés et le frontend).

Pour lancer les services assurez vous d’avoir lancé Docker Desktop puis, ouvrez un terminal et utilisez la commande docker compose up dans le dossier avec le fichier docker-compose.yml. Pour arrêter les services faites Ctrl + C dans le terminal.

Les capteurs simulés envoient une requête toutes les 60 secondes au backend.

Développement des routes

À partir de maintenant votre objectif est de coder les différentes routes nécessaires pour le frontend et les capteurs. Pour l’instant nous ne cherchons pas à sauvegarder les données reçues. Vous pouvez vous concentrer sur la forme des données JSON que vos routes doivent retourner.

Vous pouvez gérer une persistence limitée en gardant les informations en mémoire dans des listes ou retourner de fausses informations.

Le détail du fonctionnement des routes vous est donné de façon standardisée. tout d’abord la méthode HTTP utilisée, puis l’URL avec de potentiels arguments dénotés avec : (ex. /hello/:name).

Ensuite :

  • une description de ce que retourne la route
  • un exemple de payload lorsque c’est pertinent
  • un exemple de réponse
  • des potentiels codes d’erreurs à retourner

Des capteurs au backend

POST /ingress/windturbine

Used by wind turbine sensors to push data to the server. The request payload is a JSON string with the following structure:

{
    "windturbine": 1, // turbine ID in database
    "timestamp": 1741334062, // date of the measure
    "data": {
        "speed": 123.4, // speed of the turbine blade in rpm
        "power": 123.4  // generated power by the turbine in W
    }
}

Route should process the json, save its data. Note that you also should compute the new total_energy_produced value based on the power reported (you can assume the interval between two datapoints to always be 60 seconds).

If there is no wind turbine with the id provided route must respond with a 404 error. If there is an error in the json payload route must respond with a 500 error.

If everything is correct, route must respond with the following JSON:

{
    "status": "success"
}

UDP 12345

Used by solar panel sensors to push data to the server.

The payload is a : separated string with the following structure: id:temperature:power:timestamp.

For instance, 2:25.4:523.6:1741334062 is parsed in:

  • solar panel ID: 2
  • temperature: 25.4°C
  • power: 523.6W
  • timestamp: 1741334062

Similarly to the wind turbine, you should also create a new datapoint for total_energy_produced.

Sensors do not expect any response.

From backend to the frontend

General comment, when returning JSON description of entities. If no other format is specified you must convert the list of object to a list of their IDs.

For instance, in the entity Person, the relation Person::grid is represented as a simple integer and Person::sensors is represented by an array of integers.

GET /persons

Return a JSON array containing all person IDs in database.

Example response for this request:

[1, 2]

GET /person/:id

Return a JSON object that describes the person.

Example response for this request

{
  "id": 1,
  "first_name": "George",
  "last_name": "Abitbol",
  "grid": 1,
  "owned_sensors": [
    1,
    2
  ]
}

Route should return 404 if no person with the provided ID exist.

POST /person/:id

Updates the person with the corresponding id in database. Expect a JSON payload containing the new values. If an attribute is present in the JSON its value overrides the old one. If an attribute is missing in the JSON the old value is kept unchanged.

Example of JSON payload:

{
  "first_name": "Émile",
  "last_name": "Zola",
  "grid": 1,
  "owned_sensors": [1, 2]
}

You can test updating a person here.

Returns 404 if no person corresponds to the id. Returns 200 if the update is successful. Returns 500 if an error occurred during update.

DELETE /person/:id

Deletes the person with the corresponding id.

Delete Person 1

Returns 200 if the person has been suppressed without error. Returns 404 error if no person with this id exists. Returns 500 if an error occurred during suppression.

PUT /person

Add a new person to the database.

This route expects a JSON formatted payload that contains the data of the person to create. Attributes grid, first_name and last_names are mandatory, owned_sensors is optional.

{
  "first_name": "Émile",
  "last_name": "Zola",
  "grid": 1,
  "owned_sensors": [1, 2]
}

You can test adding a new person here.

Returns a 500 error if no JSON is provided or if first name, last name or grid are missing. Returns a JSON object with the id of the created person.

Exemple response:

{
  "id": 42
}

GET /grids

Returns a list of al grids ID.

Example result of /grids:

[1]

GET /grid/:id

Returns a JSON description of the grid with the specified ID.

Example of /grid/:id:

{
  "id": 1,
  "name": "La Chantrerie",
  "description": "smart grid du quartier de la Chantrerie",
  "users": [
    1,
    2
  ],
  "sensors": [
    3,
    4,
    1,
    5,
    2,
    6
  ]
}

Returns a 404 error if id no grid with corresponding id is found Return a JSON object otherwise

GET /grid/:id/production and /grid/:id/consumption

Returns the total production / consumption of the grid.

Exemple of /grid/1/production:

4439476.1618367

Example of /grid/1/consumption:

1605381.1528419708

Returns 404 if no grid with the id is found, Returns the value otherwise.

GET /sensor/:id

Return a JSON object containing all details of sensor with the given id. Response MUST contain all specific informations, e.g. blade_length for a wind turbine or efficiency for a solar panel.

Example /sensor/2 response (test here):

{
  "id": 2,
  "name": "Éolienne 1",
  "description": "l'éolienne à côté de Polytech",
  "kind": "WindTurbine",
  "grid": 1,
  "available_measurements": [
    3,
    4
  ],
  "owners": [
    1,
    2
  ],
  "power_source": "wind",
  "height": 30.0,
  "blade_length": 10.0
}

Example /sensor/4 response (test here):

{
  "id": 4,
  "name": "Chargeur 2",
  "description": "un autre chargeur de voitures",
  "kind": "EVCharger",
  "grid": 1,
  "available_measurements": [],
  "owners": [],
  "max_power": 600.0,
  "type": "type 2",
  "maxAmp": 20,
  "voltage": 380
}

Returns 404 if the id does not correspond to a sensor.

GET /sensors/:kind

Return a JSON array of all IDs of sensors with the given kind. Valid kinds are:

  • SolarPanel
  • WindTurbine
  • EVCharger

Example /sensors/EVCharger (test here)

[ 3, 4 ]

It returns an empty list if kind is not correct or if no sensors of this is found.

GET /consumers, GET /producers

Return a JSON object containing a list of all consumers (resp. producers).

Example /producers response (test here):

[
  {
    "id": 1,
    "name": "panneau solaire 1",
    "description": "une description",
    "kind": "SolarPanel",
    "grid": 1,
    "available_measurements": [
      1,
      2
    ],
    "owners": [
      1
    ],
    "power_source": "solar",
    "efficiency": 0.0
  },
  {
    "id": 2,
    "name": "Éolienne 1",
    "description": "l'éolienne à côté de Polytech",
    "kind": "WindTurbine",
    "grid": 1,
    "available_measurements": [
      3,
      4
    ],
    "owners": [
      1,
      2
    ],
    "power_source": "wind",
    "height": null,
    "blade_length": null
  },
  ...
]

FIXME: specs & frontend expect to have all specific info of sensors daughters classes, but backend only send sensor+{consumer,producer} info, leaving specific info with default value (see SQL native queries)

POST /sensor/:id

Updates a sensor with the given id. Expects a JSON payload with the new informations. Any field of the sensor can be updated. Fields present in the JSON that do not exist in the sensor are ignored (e.g. an height field for and EV Charger).

Exemple of JSON payload (test here):

{
  // for all sensors
  "name": "new name of the sensor",
  "description": "new description",
  "owners": [1, 2],

  // if sensor is a producer
  "power_source": "wind",

  // if sensor is a consumer
  "max_power": 123.456,

  // if sensor is a solar panel
  "efficiency": 123.456,

  // if sensor is a wind turbine
  "height": 12.2,
  "blade_length": 123.2,

  // if sensor is an EV charger
  "type": "AC",
  "voltage": 230,
  "maxAmp": 200
}

Returns 404 if not sensor with id exists Returns 200 if update is successful

GET /measurement/:id

Returns a JSON object representing a measurement with the given id.

Example of /measurement/1 (test here):

{
  "id": 1,
  "sensor": 1,
  "name": "temperature",
  "unit": "C°"
}

Returns a 404 error if no measurement with given id is found.

GET /measurement/:id/values

Returns a JSON object representing a measurement and its values. from and to query parameters can be used to limit values returns. If from is not specified, default to 0. If to is not specified, default to 2147483646.

Exemple /measurement/3/values (test here):

{
  "sensor_id": 1,
  "measurement_id": 3,
  "values": [
    {
      "timestamp": 1743513408,
      "value": 18008.5554197711
    },
    {
      "timestamp": 1743513468,
      "value": 35159.3868807908
    },
...
    {
      "timestamp": 1743516288,
      "value": 1007616.09980386
    },
    {
      "timestamp": 1743516348,
      "value": 1030007.18208945
    }
  ]
}

Example of /measurement/13/values?from=1743515688&to=1743515808 (test here)

{
  "sensor_id": 1,
  "measurement_id": 3,
  "values": [
    {
      "timestamp": 1743515688,
      "value": 769706.455455274
    },
    {
      "timestamp": 1743515748,
      "value": 792894.941526991
    },
    {
      "timestamp": 1743515808,
      "value": 817240.692377831
    }
  ]
}