Move project documentation to its own folder
This commit is contained in:
L-diy
143
README.md
143
README.md
@@ -1,16 +1,24 @@
|
||||
# 2023-Webservices_And_Applications
|
||||
## Used Libs, compiler and apps
|
||||
|
||||
- lwip version 2.1.2
|
||||
- CubeIDE version 1.12.1
|
||||
- STM32CubeMX version 6.8.1
|
||||
- Firmware Lib (stm32f7) 1.17.1
|
||||
# 2023 — Webservices and Applications
|
||||
## Table of Contents
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Used Libs, compiler and apps](#used-libs-compiler-and-apps)
|
||||
- [Tasks](#tasks)
|
||||
- [Style Guide](#style-guide)
|
||||
- [Editor Configuration](#editor-configuration)
|
||||
- [Commit Messages Conventions](#commit-messages-conventions)
|
||||
- [Documentation](#documentation)
|
||||
|
||||
## Tasks
|
||||
Make for each task a sperate c and h file. The name of the file is the name of the task.
|
||||
This way we can keep the code clean.
|
||||
|
||||
[tasks_and_taskowners.md](tasks_and_taskowners.md)
|
||||
## Used Libs, Compiler and Apps
|
||||
- lwip version 2.1.2
|
||||
- CubeIDE version 1.12.1
|
||||
- STM32CubeMX version 6.8.1
|
||||
- Firmware Lib (stm32f7) 1.17.1
|
||||
|
||||
## Tasks
|
||||
Make for each task a separate c and h file. The name of the file is the name of the task.
|
||||
This way we can keep the code clean.
|
||||
|
||||
[tasks_and_taskowners.md](tasks_and_taskowners.md)
|
||||
|
||||
## Style Guide
|
||||
To maintain a consistent and clean codebase, follow the [style guide](style_guide.md). This document provides detailed instructions on naming conventions, code structure, and commenting practices.
|
||||
@@ -30,106 +38,23 @@ You can choose from the following options:
|
||||
- For Eclipse-based editors, including STM32CubeIDE.
|
||||
- You can import it within eclipse settings, `Preferences -> LANGUAGE -> Code Style -> Formatter` tab.
|
||||
|
||||
## Logging and Debugging Messages
|
||||
The logging system is designed to make log messages clearer and improve their uniformity across the project.
|
||||
It makes it easier to see where a log message comes from and what its verbosity is.
|
||||
## Commit Messages Conventions
|
||||
The subject line of a commit message should follow the following rules:
|
||||
- Short and descriptive (max 50 chars)
|
||||
- In imperative present tense
|
||||
- Capitalized
|
||||
- Not end with a period
|
||||
|
||||
To use the logging system, include `log.h` in your source file, and use the following macros to print log messages:
|
||||
```c
|
||||
LOG_DEBUG(TAG, fmt, ...)
|
||||
LOG_INFO(TAG, fmt, ...)
|
||||
LOG_WARN(TAG, fmt, ...)
|
||||
LOG_CRIT(TAG, fmt, ...)
|
||||
LOG_FATAL(TAG, fmt, ...)
|
||||
Example:
|
||||
```
|
||||
The same format specifiers as in `printf` can be used.
|
||||
|
||||
The `TAG` parameter is a string that identifies the source of the log message.
|
||||
It is recommended to use one tag for each source file / module, and to name the tag after the source file / module.
|
||||
See the example below.
|
||||
|
||||
### Global Log Level
|
||||
You can control the verbosity of the logging output by setting a global log level in `log.h`.
|
||||
This log level filters out messages with a lower priority.
|
||||
|
||||
### Custom Log Levels
|
||||
before you include `log.h`, you can define custom log levels by defining the following macros:
|
||||
```c
|
||||
// All log messages will be printed
|
||||
#define LOGGER_LEVEL_ALL
|
||||
#include "log.h"
|
||||
Implement access right management
|
||||
```
|
||||
|
||||
```c
|
||||
// Info and higher priority messages will be printed
|
||||
#define LOGGER_LEVEL_INFO
|
||||
#include "log.h"
|
||||
```
|
||||
The body of a commit message may be used to explain the what and why of a commit.
|
||||
|
||||
```c
|
||||
// Only warnings and errors will be printed
|
||||
#define LOGGER_LEVEL_WARN
|
||||
#include "log.h"
|
||||
```
|
||||
## Documentation
|
||||
Documentation is placed in the [docs](docs) folder.
|
||||
If your part needs documentation (e.g. how to use tcp cmd interface), add a markdown file in the above-mentioned folder.
|
||||
|
||||
```c
|
||||
// Only log messages with level ERROR will be printed
|
||||
#define LOGGER_LEVEL_CRITICAL
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
```c
|
||||
// Only log messages with level ERROR will be printed
|
||||
#define LOGGER_LEVEL_FATAL
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
### Colorful Log Messages
|
||||
For improved readability, log messages can be printed in color by defining `LOGGER_USE_COLOR` in `log.h` or before you include `log.h`. \
|
||||
Default is `0`
|
||||
|
||||
### Log Output Format
|
||||
Each log entry is formatted to include the following information:
|
||||
|
||||
- Log level ([Debug], [Info], [Warn], [Critical], [Fatal])
|
||||
- Timestamp (in milliseconds since boot)
|
||||
- Tag
|
||||
- The log message
|
||||
|
||||
For instance, a log entry may look like this:
|
||||
|
||||
`[Info] (2009) [LTDC]: This is a log message`
|
||||
|
||||
### Example
|
||||
```c
|
||||
#define LOGGER_LEVEL_INFO
|
||||
#include "log.h"
|
||||
|
||||
// Don't use a define for the tag, as the pointer to the tag is used
|
||||
static const char *TAG = "main";
|
||||
|
||||
int main(void) {
|
||||
|
||||
LOG_DEBUG(TAG, "This message will not be printed");
|
||||
LOG_INFO(TAG, "This message will be printed");
|
||||
LOG_WARN(TAG, "This message will be printed");
|
||||
LOG_CRIT(TAG, "This message will be printed");
|
||||
LOG_FATAL(TAG, "This message will be printed");
|
||||
|
||||
for (int i = 0; i < 3; i++) {
|
||||
LOG_INFO(TAG, "Iteration %d of %d", i, 3);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
Result:
|
||||
```
|
||||
[Info] (2009) main: This message will be printed
|
||||
[Warning] (2026) main: This message will be printed
|
||||
[CRITICAL] (2033) main: This message will be printed
|
||||
[FATAL] (2040) main: This message will be printed
|
||||
[Info] (2040) main: Iteration 0 of 3
|
||||
[Info] (2047) main: Iteration 1 of 3
|
||||
[Info] (2054) main: Iteration 2 of 3
|
||||
```
|
||||
This folder contains the following documents:
|
||||
- [logger.md](docs/logger.md): Logging and Debugging Messages
|
||||
|
||||
103
docs/logger.md
Normal file
103
docs/logger.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Logging and Debugging Messages
|
||||
The logging system is designed to make log messages clearer and improve their uniformity across the project.
|
||||
It makes it easier to see where a log message comes from and what its verbosity is.
|
||||
|
||||
To use the logging system, include `log.h` in your source file, and use the following macros to print log messages:
|
||||
```c
|
||||
LOG_DEBUG(TAG, fmt, ...)
|
||||
LOG_INFO(TAG, fmt, ...)
|
||||
LOG_WARN(TAG, fmt, ...)
|
||||
LOG_CRIT(TAG, fmt, ...)
|
||||
LOG_FATAL(TAG, fmt, ...)
|
||||
```
|
||||
The same format specifiers as in `printf` can be used.
|
||||
|
||||
The `TAG` parameter is a string that identifies the source of the log message.
|
||||
It is recommended to use one tag for each source file / module, and to name the tag after the source file / module.
|
||||
See the example below.
|
||||
|
||||
## Global Log Level
|
||||
You can control the verbosity of the logging output by setting a global log level in `log.h`.
|
||||
This log level filters out messages with a lower priority.
|
||||
|
||||
## Custom Log Levels
|
||||
before you include `log.h`, you can define custom log levels by defining the following macros:
|
||||
```c
|
||||
// All log messages will be printed
|
||||
#define LOGGER_LEVEL_ALL
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
```c
|
||||
// Info and higher priority messages will be printed
|
||||
#define LOGGER_LEVEL_INFO
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
```c
|
||||
// Only warnings and errors will be printed
|
||||
#define LOGGER_LEVEL_WARN
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
```c
|
||||
// Only log messages with level ERROR will be printed
|
||||
#define LOGGER_LEVEL_CRITICAL
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
```c
|
||||
// Only log messages with level ERROR will be printed
|
||||
#define LOGGER_LEVEL_FATAL
|
||||
#include "log.h"
|
||||
```
|
||||
|
||||
## Colorful Log Messages
|
||||
For improved readability, log messages can be printed in color by defining `LOGGER_USE_COLOR` in `log.h` or before you include `log.h`. \
|
||||
Default is `0`
|
||||
|
||||
## Log Output Format
|
||||
Each log entry is formatted to include the following information:
|
||||
|
||||
- Log level ([Debug], [Info], [Warn], [Critical], [Fatal])
|
||||
- Timestamp (in milliseconds since boot)
|
||||
- Tag
|
||||
- The log message
|
||||
|
||||
For instance, a log entry may look like this:
|
||||
|
||||
`[Info] (2009) [LTDC]: This is a log message`
|
||||
|
||||
## Example
|
||||
```c
|
||||
#define LOGGER_LEVEL_INFO
|
||||
#include "log.h"
|
||||
|
||||
// Don't use a define for the tag, as the pointer to the tag is used
|
||||
static const char *TAG = "main";
|
||||
|
||||
int main(void) {
|
||||
|
||||
LOG_DEBUG(TAG, "This message will not be printed");
|
||||
LOG_INFO(TAG, "This message will be printed");
|
||||
LOG_WARN(TAG, "This message will be printed");
|
||||
LOG_CRIT(TAG, "This message will be printed");
|
||||
LOG_FATAL(TAG, "This message will be printed");
|
||||
|
||||
for (int i = 0; i < 3; i++) {
|
||||
LOG_INFO(TAG, "Iteration %d of %d", i, 3);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
Result:
|
||||
```
|
||||
[Info] (2009) [main]: This message will be printed
|
||||
[Warning] (2026) [main]: This message will be printed
|
||||
[CRITICAL] (2033) [main]: This message will be printed
|
||||
[FATAL] (2040) [main]: This message will be printed
|
||||
[Info] (2040) [main]: Iteration 0 of 3
|
||||
[Info] (2047) [main]: Iteration 1 of 3
|
||||
[Info] (2054) [main]: Iteration 2 of 3
|
||||
```
|
||||
Reference in New Issue
Block a user