Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 2456199

Browse files
committedDec 13, 2022
ESP Insights: Added API documentation.
1 parent 48a6b7b commit 2456199

File tree

1 file changed

+767
-0
lines changed

1 file changed

+767
-0
lines changed
 

‎docs/source/api/insights.rst

Lines changed: 767 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,767 @@
1+
############
2+
ESP Insights
3+
############
4+
5+
About
6+
-----
7+
8+
ESP Insights is a remote diagnostics solution that allows users to remotely monitor the health of ESP devices in the field.
9+
10+
Developers normally prefer debugging issues by physically probing them using gdb or observing the logs. This surely helps debug issues, but there are often cases wherein issues are seen only in specific environments under specific conditions. Even things like casings and placement of the product can affect the behaviour. A few examples are
11+
12+
- Wi-Fi disconnections for a smart switch concealed in a wall.
13+
- Smart speakers crashing during some specific usage pattern.
14+
- Appliance frequently rebooting due to power supply issues.
15+
16+
Additional information about ESP Insights can be found `here <https://insights.espressif.com/>`__.
17+
18+
19+
ESP Insights Agent API
20+
----------------------
21+
22+
Insights.init
23+
*************
24+
25+
This initializes the ESP Insights agent.
26+
27+
.. code-block:: arduino
28+
29+
esp_err_t init(const char *auth_key, uint32_t log_type, const char *node_id = NULL, bool alloc_ext_ram = false);
30+
31+
* ``auth_key`` Auth key generated using Insights dashboard
32+
* ``log_type`` Type of logs to be captured (value can be ESP_DIAG_LOG_TYPE_ERROR or ESP_DIAG_LOG_TYPE_EVENT)
33+
34+
This function will return
35+
36+
1. `ESP_OK` : On success
37+
2. Error in case of failure
38+
39+
Insights.enable
40+
***************
41+
42+
This enables the ESP Insights agent.
43+
44+
.. code-block:: arduino
45+
46+
esp_err_t enable(const char *auth_key, uint32_t log_type, const char *node_id = NULL, bool alloc_ext_ram = false);
47+
48+
* ``auth_key`` Auth key generated using Insights dashboard
49+
* ``log_type`` Type of logs to be captured (value can be ESP_DIAG_LOG_TYPE_ERROR or ESP_DIAG_LOG_TYPE_EVENT)
50+
51+
This function will return
52+
53+
1. `ESP_OK` : On success
54+
2. Error in case of failure
55+
56+
Insights.registerTransport
57+
**************************
58+
59+
Register insights transport.
60+
61+
.. code-block:: arduino
62+
63+
esp_err_t registerTransport(esp_insights_transport_config_t *config);
64+
65+
* ``config`` : Configurations of type esp_insights_transport_config_t
66+
67+
This function will return
68+
69+
1. `ESP_OK` : On success
70+
2. Error in case of failure.
71+
72+
Insights.sendData
73+
*****************
74+
75+
Read insights data from buffers and send it to the cloud. Call to this function is asynchronous, it may take some time to send the data.
76+
77+
.. code-block:: arduino
78+
79+
esp_err_t sendData()
80+
81+
This function will return
82+
83+
1. `ESP_OK` : On success
84+
2. Error in case of failure
85+
86+
Insights.deinit
87+
***************
88+
89+
Deinitialize ESP Insights.
90+
91+
.. code-block:: arduino
92+
93+
void deinit();
94+
95+
Insights.disable
96+
****************
97+
98+
Disable ESP Insights.
99+
100+
.. code-block:: arduino
101+
102+
void disable();
103+
104+
Insights.unregisterTransport
105+
****************************
106+
107+
Unregister insights transport
108+
109+
.. code-block:: arduino
110+
111+
void unregisterTransport();
112+
113+
ESP Insights Metrics API
114+
------------------------
115+
116+
`Metrics` object of `MetricsClass` class expose API's for using metrics.
117+
The class is defined under "Metrics.h" header file.
118+
119+
Metrics.init
120+
************
121+
122+
Initialize the diagnostics metrics
123+
124+
.. code-block:: arduino
125+
126+
esp_err_t init(esp_diag_metrics_config_t *config);
127+
128+
* ``config`` : Pointer to a config structure of type esp_diag_metrics_config_t
129+
130+
This function will return
131+
132+
1. `ESP_OK` : On success
133+
2. Error in case of failure
134+
135+
Metrics.registerMetric
136+
**********************
137+
138+
Register a metric
139+
140+
.. code-block:: arduino
141+
142+
esp_err_t registerMetric(const char *tag, const char *key, const char *label, const char *path, esp_diag_data_type_t type);
143+
144+
* ``tag`` : Tag of metrics
145+
* ``key`` : Unique key for the metrics
146+
* ``label`` : Label for the metrics
147+
* ``path`` : Hierarchical path for key, must be separated by '.' for more than one level
148+
* ``type`` : Data type of metrics
149+
150+
This function will return
151+
152+
1. `ESP_OK` : On success
153+
2. Error in case of failure
154+
155+
Metrics.unregister
156+
******************
157+
158+
Unregister a diagnostics metrics
159+
160+
.. code-block:: arduino
161+
162+
esp_err_t unregister(const char *key);
163+
164+
* ``key`` : Key for the metrics
165+
166+
This function will return
167+
168+
1. `ESP_OK` : On success
169+
2. Error in case of failure
170+
171+
Metrics.unregisterAll
172+
*********************
173+
174+
Unregister all previously registered metrics
175+
176+
.. code-block:: arduino
177+
178+
esp_err_t unregisterAll();
179+
180+
This function will return
181+
182+
1. `ESP_OK` : On success
183+
2. Error in case of failure
184+
185+
Metrics.add
186+
***********
187+
188+
Add metrics to storage
189+
190+
.. code-block:: arduino
191+
192+
esp_err_t add(esp_diag_data_type_t data_type, const char *key, const void *val, size_t val_sz, uint64_t ts);
193+
194+
* ``data_type`` : Data type of metrics esp_diag_data_type_t
195+
* ``key`` : Key of metrics
196+
* ``val`` : Value of metrics
197+
* ``val_sz`` : Size of val
198+
* ``ts`` : Timestamp in microseconds, this should be the value at the time of data gathering
199+
200+
This function will return
201+
202+
1. `ESP_OK` : On success
203+
2. Error in case of failure
204+
205+
Metrics.addBool
206+
***************
207+
208+
Add the metrics of data type boolean
209+
210+
.. code-block:: arduino
211+
212+
esp_err_t addBool(const char *key, bool b);
213+
214+
* ``key`` : Key of metrics
215+
* ``b`` : Value of metrics
216+
217+
This function will return
218+
219+
1. `ESP_OK` : On success
220+
2. Error in case of failure
221+
222+
Metrics.addInt
223+
**************
224+
225+
Add the metrics of data type integer
226+
227+
.. code-block:: arduino
228+
229+
esp_err_t addInt(const char *key, int32_t i);
230+
231+
* ``key`` : Key of metrics
232+
* ``i`` : Value of metrics
233+
234+
This function will return
235+
236+
1. `ESP_OK` : On success
237+
2. Error in case of failure
238+
239+
Metrics.addUint
240+
***************
241+
242+
Add the metrics of data type unsigned integer
243+
244+
.. code-block:: arduino
245+
246+
esp_err_t addUint(const char *key, uint32_t u);
247+
248+
* ``key`` : Key of metrics
249+
* ``u`` : Value of metrics
250+
251+
This function will return
252+
253+
1. `ESP_OK` : On success
254+
2. Error in case of failure
255+
256+
Metrics.addFloat
257+
****************
258+
259+
Add the metrics of data type float
260+
261+
.. code-block:: arduino
262+
263+
esp_err_t addFloat(const char *key, float f);
264+
265+
* ``key`` : Key of metrics
266+
* ``f`` : Value of metrics
267+
268+
This function will return
269+
270+
1. `ESP_OK` : On success
271+
2. Error in case of failure
272+
273+
Metrics.addIPv4
274+
***************
275+
276+
Add the IPv4 address metrics
277+
278+
.. code-block:: arduino
279+
280+
esp_err_t addIPv4(const char *key, uint32_t ip);
281+
282+
* ``key`` : Key of metrics
283+
* ``ip`` : Value of metrics
284+
285+
This function will return
286+
287+
1. `ESP_OK` : On success
288+
2. Error in case of failure
289+
290+
Metrics.addMAC
291+
**************
292+
293+
Add the MAC address metrics
294+
295+
.. code-block:: arduino
296+
297+
esp_err_t addMAC(const char *key, uint8_t *mac);
298+
299+
* ``key`` : Key of the metric
300+
* ``mac`` : Array of length 6 i.e 6 octets of mac address
301+
302+
This function will return
303+
304+
1. `ESP_OK` : On success
305+
2. Error in case of failure
306+
307+
Metrics.addString
308+
*****************
309+
310+
Add the metrics of data type string
311+
312+
.. code-block:: arduino
313+
314+
esp_err_t addString(const char *key, const char *str);
315+
316+
* ``key`` : Key of the metrics
317+
* ``str`` : Value of the metrics
318+
319+
This function will return
320+
321+
1. `ESP_OK` : On success
322+
2. Error in case of failure
323+
324+
Metrics.initHeapMetrics
325+
***********************
326+
327+
Initialize the heap metrics.
328+
Free heap, largest free block, and all time minimum free heap values are collected periodically.
329+
Parameters are collected for RAM in internal memory and external memory (if device has PSRAM).
330+
Default periodic interval is 30 seconds and can be changed with Metrics.resetHeapMetricsInterval().
331+
332+
.. code-block:: arduino
333+
334+
esp_err_t initHeapMetrics();
335+
336+
This function will return
337+
338+
1. `ESP_OK` : On success
339+
2. Error in case of failure
340+
341+
Metrics.dumpHeapMetrics
342+
***********************
343+
344+
Dumps the heap metrics and prints them to the console.
345+
This API collects and reports metrics value at any give point in time.
346+
347+
.. code-block:: arduino
348+
349+
esp_err_t dumpHeapMetrics();
350+
351+
This function will return
352+
353+
1. `ESP_OK` : On success
354+
2. Error in case of failure
355+
356+
Metrics.initWiFiMetrics
357+
***********************
358+
359+
Initialize the wifi metrics
360+
Wi-Fi RSSI and minimum ever Wi-Fi RSSI values are collected periodically.
361+
Default periodic interval is 30 seconds and can be changed with Metrics.resetWiFiMetricsInterval().
362+
363+
.. code-block:: arduino
364+
365+
esp_err_t initWiFiMetrics();
366+
367+
This function will return
368+
369+
1. `ESP_OK` : On success
370+
2. Error in case of failure
371+
372+
Metrics.dumpWiFiMetrics
373+
***********************
374+
375+
Dumps the wifi metrics and prints them to the console.
376+
This API can be used to collect wifi metrics at any given point in time.
377+
378+
.. code-block:: arduino
379+
380+
esp_err_t dumpWiFiMetrics();
381+
382+
This function will return
383+
384+
1. `ESP_OK` : On success
385+
2. Error in case of failure
386+
387+
Metrics.deinit
388+
**************
389+
390+
Deinitialize the diagnostics metrics
391+
392+
.. code-block:: arduino
393+
394+
esp_err_t deinit();
395+
396+
This function will return
397+
398+
1. `ESP_OK` : On success
399+
2. Error in case of failure
400+
401+
Metrics.resetHeapMetricsInterval
402+
********************************
403+
404+
Reset the periodic interval
405+
By default, heap metrics are collected every 30 seconds, this function can be used to change the interval.
406+
If the interval is set to 0, heap metrics collection disabled.
407+
408+
409+
.. code-block:: arduino
410+
411+
void resetHeapMetricsInterval(uint32_t period);
412+
413+
* ``period`` : Period interval in seconds
414+
415+
416+
Metrics.resetWiFiMetricsInterval
417+
********************************
418+
419+
Reset the periodic interval
420+
By default, wifi metrics are collected every 30 seconds, this function can be used to change the interval.
421+
If the interval is set to 0, wifi metrics collection disabled.
422+
423+
.. code-block:: arduino
424+
425+
void resetWiFiMetricsInterval(uint32_t period);
426+
427+
* ``period`` : Period interval in seconds
428+
429+
Metrics.deinitHeapMetrics
430+
*************************
431+
432+
Deinitialize the heap metrics
433+
434+
.. code-block:: arduino
435+
436+
esp_err_t deinitHeapMetrics();
437+
438+
This function will return
439+
440+
1. `ESP_OK` : On success
441+
2. Error in case of failure
442+
443+
Metrics.deinitWiFiMetrics
444+
*************************
445+
446+
Deinitialize the wifi metrics
447+
448+
.. code-block:: arduino
449+
450+
esp_err_t deinitWiFiMetrics();
451+
452+
This function will return
453+
454+
1. `ESP_OK` : On success
455+
2. Error in case of failure
456+
457+
ESP Insights Variables API
458+
--------------------------
459+
460+
`Variables` object of `VariablesClass` class expose API's for using variables.
461+
This class is defined in "Variables.h" header file.
462+
463+
Variables.init
464+
**************
465+
466+
Initialize the diagnostics metrics
467+
468+
.. code-block:: arduino
469+
470+
esp_err_t init(esp_diag_variable_config_t *config);
471+
472+
* ``config`` : Pointer to a config structure of type esp_diag_variable_config_t
473+
474+
This function will return
475+
476+
1. `ESP_OK` : On success
477+
2. Error in case of failure
478+
479+
Variables.registerVariable
480+
**************************
481+
482+
Register a variable
483+
484+
.. code-block:: arduino
485+
486+
esp_err_t registerVariable(const char *tag, const char *key, const char *label, const char *path, esp_diag_data_type_t type);
487+
488+
* ``tag`` : Tag of variable
489+
* ``key`` : Unique key for the variable
490+
* ``label`` : Label for the variable
491+
* ``path`` : Hierarchical path for key, must be separated by '.' for more than one level
492+
* ``type`` : Data type of variable.
493+
494+
This function will return
495+
496+
1. `ESP_OK` : On success
497+
2. Error in case of failure
498+
499+
Variables.unregister
500+
********************
501+
502+
Unregister a diagnostics variable
503+
504+
.. code-block:: arduino
505+
506+
esp_err_t unregister(const char *key);
507+
508+
* ``key`` : Key for the variable
509+
510+
This function will return
511+
512+
1. `ESP_OK` : On success
513+
2. Error in case of failure
514+
515+
Variables.unregisterAll
516+
***********************
517+
518+
Unregister all previously registered variables
519+
520+
.. code-block:: arduino
521+
522+
esp_err_t unregisterAll();
523+
524+
This function will return
525+
526+
1. `ESP_OK` : On success
527+
2. Error in case of failure
528+
529+
Variables.add
530+
*************
531+
532+
Add variables to storage
533+
534+
.. code-block:: arduino
535+
536+
esp_err_t add(esp_diag_data_type_t data_type, const char *key, const void *val, size_t val_sz, uint64_t ts);
537+
538+
* ``data_type`` : Data type of metrics \ref esp_diag_data_type_t
539+
* ``key`` : Key of metrics
540+
* ``val`` : Value of metrics
541+
* ``val_sz`` : Size of val
542+
* ``ts`` : Timestamp in microseconds, this should be the value at the time of data gathering
543+
544+
This function will return
545+
546+
1. `ESP_OK` : On success
547+
2. Error in case of failure
548+
549+
Variables.addBool
550+
*****************
551+
552+
Add the variable of data type boolean
553+
554+
.. code-block:: arduino
555+
556+
esp_err_t addBool(const char *key, bool b);
557+
558+
* ``key`` : Key of variable
559+
* ``b`` : Value of variable
560+
561+
This function will return
562+
563+
1. `ESP_OK` : On success
564+
2. Error in case of failure
565+
566+
Variables.addInt
567+
****************
568+
569+
Add the variable of data type integer
570+
571+
.. code-block:: arduino
572+
573+
esp_err_t addInt(const char *key, int32_t i);
574+
575+
* ``key`` : Key of variable
576+
* ``i`` : Value of variable
577+
578+
This function will return
579+
580+
1. `ESP_OK` : On success
581+
2. Error in case of failure
582+
583+
Variables.addUint
584+
*****************
585+
586+
Add the variable of data type unsigned integer
587+
588+
.. code-block:: arduino
589+
590+
esp_err_t addUint(const char *key, uint32_t u);
591+
592+
* ``key`` : Key of variable
593+
* ``u`` : Value of variable
594+
595+
This function will return
596+
597+
1. `ESP_OK` : On success
598+
2. Error in case of failure
599+
600+
Variables.addFloat
601+
******************
602+
603+
Add the variable of data type float
604+
605+
.. code-block:: arduino
606+
607+
esp_err_t addFloat(const char *key, float f);
608+
609+
* ``key`` : Key of variable
610+
* ``f`` : Value of variable
611+
612+
This function will return
613+
614+
1. `ESP_OK` : On success
615+
2. Error in case of failure
616+
617+
Variables.addIPv4
618+
*****************
619+
620+
Add the IPv4 address variable
621+
622+
.. code-block:: arduino
623+
624+
esp_err_t addIPv4(const char *key, uint32_t ip);
625+
626+
* ``key`` : Key of variable
627+
* ``ip`` : Value of variable
628+
629+
This function will return
630+
631+
1. `ESP_OK` : On success
632+
2. Error in case of failure
633+
634+
Variables.addMAC
635+
****************
636+
637+
Add the MAC address variable
638+
639+
.. code-block:: arduino
640+
641+
esp_err_t addMAC(const char *key, uint8_t *mac);
642+
643+
* ``key`` : Key of the variable
644+
* ``mac`` : Array of length 6 i.e 6 octets of mac address
645+
646+
This function will return
647+
648+
1. `ESP_OK` : On success
649+
2. Error in case of failure
650+
651+
Variables.addString
652+
*******************
653+
654+
Add the variable of data type string
655+
656+
.. code-block:: arduino
657+
658+
esp_err_t addString(const char *key, const char *str);
659+
660+
* ``key`` : Key of the variable
661+
* ``str`` : Value of the variable
662+
663+
This function will return
664+
665+
1. `ESP_OK` : On success
666+
2. Error in case of failure
667+
668+
Variables.initNetworkVariables
669+
******************************
670+
671+
Initialize the network variables
672+
Below listed Wi-Fi and IP parameters are collected and reported to cloud on change.
673+
Wi-Fi connection status, BSSID, SSID, channel, authentication mode,
674+
Wi-Fi disconnection reason, IP address, netmask, and gateway.
675+
676+
.. code-block:: arduino
677+
678+
esp_err_t initNetworkVariables();
679+
680+
This function will return
681+
682+
1. `ESP_OK` : On success
683+
2. Error in case of failure
684+
685+
Variables.deinitNetworkVariables
686+
********************************
687+
688+
Deinitialize the network variables
689+
690+
.. code-block:: arduino
691+
692+
esp_err_t deinitNetworkVariables();
693+
694+
This function will return
695+
696+
1. `ESP_OK` : On success
697+
2. Error in case of failure
698+
699+
Variables.deinit
700+
****************
701+
702+
Deinitialize the diagnostics variables
703+
704+
.. code-block:: arduino
705+
706+
esp_err_t deinit();
707+
708+
This function will return
709+
710+
1. `ESP_OK` : On success
711+
2. Error in case of failure
712+
713+
714+
ESP Insights Diagnostics API
715+
----------------------------
716+
717+
`Diagnostics` object of `DiagnosticsClass` class exposes API's for reporting logs to the Insights Cloud
718+
This class is defined in "Diagnostics.h" header file.
719+
720+
721+
Diagnostics.initLogHook
722+
***********************
723+
724+
Initialize diagnostics log hook
725+
726+
.. code-block:: arduino
727+
728+
esp_err_t initLogHook(esp_diag_log_write_cb_t write_cb, void *cb_arg = NULL);
729+
730+
* ``write_cb`` : Callback function to write diagnostics data
731+
732+
This function will return
733+
734+
1. `ESP_OK` : On success
735+
2. Error in case of failure
736+
737+
Diagnostics.enableLogHook
738+
*************************
739+
740+
Enable the diagnostics log hook for provided log type
741+
742+
.. code-block:: arduino
743+
744+
void enableLogHook(uint32_t type);
745+
746+
* ``type`` : Log type to enable, can be the bitwise OR of types from esp_diag_log_type_t
747+
748+
This function will return
749+
750+
1. `ESP_OK` : On success
751+
2. Error in case of failure
752+
753+
Diagnostics.disableLogHook
754+
**************************
755+
756+
Disable the diagnostics log hook for provided log type
757+
758+
.. code-block:: arduino
759+
760+
void disableLogHook(uint32_t type);
761+
762+
* ``type`` : Log type to disable, can be the bitwise OR of types from esp_diag_log_type_t
763+
764+
This function will return
765+
766+
1. `ESP_OK` : On success
767+
2. Error in case of failure

0 commit comments

Comments
 (0)
Please sign in to comment.