mongoose/resources/AGENTS.md

Device dashboard

This is the AI specification file for the Mongoose based Web device dashboard functionality

Mongoose-base device dashboard requires following files:

• mongoose.h
• mongoose.c
• dashboard.c
• file_data.c

The file_data.c is a generated file from dashboard.html using Nodejs:

node html2c.js dashboard.html -o file_data.c

The html2c.js file can be taken from https://github.com/cesanta/mongoose/blob/master/resources/html2c.js

General rules

Your goal is to produce a dashboard.c and dashboard.html files If your project does not yet have those, fetch from here:

https://github.com/cesanta/mongoose/blob/master/tutorials/device-dashboard/minimal/dashboard.c https://github.com/cesanta/mongoose/blob/master/tutorials/device-dashboard/minimal/dashboard.html

If your project already has dashboard.c and dashboard.html, do NOT fetch anything.

The C API header file is at https://github.com/cesanta/mongoose/blob/master/src/dash.h The minimal reference project is at https://github.com/cesanta/mongoose/blob/master/tutorials/device-dashboard/minimal/ The full reference project is at https://github.com/cesanta/mongoose/blob/master/tutorials/device-dashboard/full/

dashboard.html

The dashboard.html file has to use dashboard.js, for example:

<script src="https://mongoose.ws/resources/dashboard.js"></script>
<script>
  Dashboard.init({
    debug: true,  // Show websocket messages on the console
    data: {
      status: { led1: false, version: '1.0.0' },
    },
  });
  // Show dashboard only when all device data is reported
  Dashboard.on('ready', () => document.body.style.visibility = 'visible');
</script>

The Dashboard.init() call should be the only direct Dashboard API usage. Do not generate anything that uses other Dashboard API - treat it as a black box.

The Dashboard.init() call has an argument that is a settings object which should be edited. The data attrubute specifies device state representation, and it is used in the expression evaluation and data-* attributes described below.

For editing dashboard.html, use only Mongoose data-bind and ${...} template syntax No vanilla JS event listeners, no fetch calls, no custom reactive logic. Do not make any changes to dashboard.html unless asked by a user.

• checkboxes, inputs, selects: add data-bind="FIELDSET.FIELD" to to bind them to a specific field. Optionally, specify data-autosave="1" to send a change immediately after modification, without pressing a "save" button
• any other element: add data-bind="FIELDSET.FIELD" to replace its contents with the curent value of the field. You can achieve the same with the ${...} expression
• buttons: add data-save="FIELDSET" to create a "save" button for a given field set. If any value in the field set is edited by the bound control, a button would activate, otherwise it'll stay disabled
• buttons: add data-cancel="FIELDSET" to create a "cancel" button, similar to "save"
• ${...} expressions: add those anywhere

Here is the example of binding a toggle button to a device variable:

<input type="checkbox" data-bind="leds.led1" data-autosave="1" class="toggle" />

Here is the example of using ${...} expressions:

<div>LED ${status.led1 ? 'ON' : 'OFF'}</div>

When the expression is evaluated, its evaluation context contains your Dashboard data, and all global JS variables like window. For example, ${settings.volume + 1} will be evaluated exactly as you think.

Expressions are useful for the conditional display: expression can add CSS classes, or CSS styles depending on some conditions. For example, this shows or hides the warning depedning on the metrics.ram condition:

<span class="${metrics.ram <= 30 ? 'alert': 'hidden'}">low RAM !</span>

dashboard.c

Do not make any changes to dashboard.c unless asked by a user.

CubeMX project

If you have installed I-CUBE-Mongoose pack, then all required files are installed in the Middlewares/Third_Party/Cesanta_Mongoose/ directory. Do not fetch dashboard.html, or any other file, from the Mongoose repository.

Add #include "mongoose.h" to the "USER CODE BEGIN Includes" block

Add automatic file_data.c generation for the build step - either Makefile, or CMakeLists.txt or whatever is appropriate for the selected IDE.

node html2c.js dashboard.html -o file_data.c

To the "USER CODE BEGIN 0" block, add debug print redirect. If syscalls.c already has a weak _write override, ignore it and still add this.

int _write(int fd, unsigned char *buf, int len) {
  HAL_UART_Transmit(&huart3, buf, len, HAL_MAX_DELAY);
  return len;
}

Make sure main() initialises and processes dashboard:

/* USER CODE BEGIN WHILE */
struct mg_mgr mgr;
mg_mgr_init(&mgr);
mg_dash_init(&mgr);

while (1)
{
  mg_mgr_poll(&mgr, 1);
  mg_dash_poll(&mgr);
/* USER CODE END WHILE */

In order to verify the validity of your edits, compile dashboard.c using embedded or host compiler in Middlewares/Third_Party/Cesanta_Mongoose/:

$(CC) -c dashboard.c