Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@PBrunot
PBrunot authored Jan 1, 2024
1 parent b1b4c2f commit 6d1ef93
Showing 1 changed file with 61 additions and 67 deletions.
128 changes: 61 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,33 +12,84 @@ Build status : [![PlatformIO CI](https://github.com/fablab-bergamo/rfid-arduino/
- A LED or NeoPixel
- RFID tags or cards for user authentication

## Other requirements
### Other requirements

- MQTT Broker on WiFi network. Board can work in offline mode with whitelisted RFID tags.

> Tested with Mosquitto. See the backend side project in [Github rfid-backend](https://github.com/fablab-bergamo/rfid-backend)
- In the <code>shelly</code> branch an experimental test with smart plugs (Shelly) over MQTT is available.

## Build environment

- Language: C++17 with ArduinoFramework for ESP32
- IDE: VSCode + Platform.io extension as a minimun
- To build, rename <code>secrets.h.example</code> to <code>secrets.h</code>.

> Platform IO can be used from command-line with <code>pio run</code>
- To build, rename <code>secrets.hpp.example</code> to <code>secrets.hpp</code>.

> Platform IO can be used from command-line without VSCode <code>pio run</code>
> CMakeList.txt is generated from platform.io, do not use other build tools directly (ESP, cmake...)
- To use hostname for MQTT server. mDNS is used by the Arduino stack built over ESP-IDF 4.4. When Arduino core for ESP will move to ESP-IDF 5.0+ an additional dependency to mDNS will be needed as mDNS is now an independent component.
- To use hostname for MQTT server, mDNS is used by the Arduino stack built over ESP-IDF 4.4. When Arduino core for ESP will move to ESP-IDF 5.0+ an additional dependency to mDNS will be needed as mDNS is now an independent component.

## TESTING

- A set a test scripts based on Platformio+Unity is included in the project.
- Currently, the only way to run the tests is to use real hardware (esp32-s3) with Platform.io command

```shell
pio test --environment esp32-s3
```

## DEMO - Testing in the browser

- Download latest <code>esp32-wokwi.zip</code> file from Github Actions / platformio.yml / Artifacts
- Extract <code>esp32-wokwi.bin</code> file from artifact ZIP
- Open WOKWI Circuit https://wokwi.com/projects/363448917434192897
- In code editor, press F1 > Upload firmware ... and pick the <code>esp32-wokwi.bin</code> file

![image](https://github.com/fablab-bergamo/rfid-arduino/assets/6236243/5c41092e-f8bf-451a-95ec-8dc6d7e07824)

- When the preprocessor constant <code>WOKWI_SIMULATION</code> is set to true:
- RFID chip is replaced with a mockup simulating random RFID tags from whitelist from time to time (<code>MockRFIDWrapper</code> class).
- A simple MQTT broker (<code>MockMQTTBroker</code> class) is run in a separate thread on esp32s2

## Configuration steps

- See <code>pins.hpp</code> to set the GPIO pins for LCD parallel interface, relay, buzzer and RFID reader SPI interface.
- See <code>conf.hpp</code> to configure LCD dimensions, timeouts, debug logs and some behaviours (e.g. time before to power off the machine)
- See <code>secrets.hpp</code> to configure network SSID/Password credentials, MQTT credentials and whitelisted RFID tags

- A configuration portal based on WiFiManager allows to configured WiFi credentials, MQTT Broker address and Shelly topic (facultative). This makes editing <code>conf.hpp</code> required only for MQTT Broker credentials settings.

> To add a white-listed RFID card, edit the tuples list <code>whitelist</code>. These RFID tags will be always authorized, even without server connection.
```c++
static constexpr WhiteList whitelist /* List of RFID tags whitelisted, regardless of connection */
{
std::make_tuple(0xAABBCCD1, FabUser::UserLevel::FABLAB_ADMIN, "ABCDEFG"),
...
std::make_tuple(0xAABBCCDA, FabUser::UserLevel::FABLAB_USER, "USER1")
};
```
> To map the switch Shelly control MQTT topic, edit the <code>machine_topic</code> under <code>conf::default_config</code> in conf.hpp file
```c++
namespace conf::default_config
{
static constexpr std::string_view mqtt_server = "127.0.0.1";
static constexpr std::string_view machine_topic = "shelly/command/switch:0"; // Set to empty to disable Shelly integration
static constexpr MachineID machine_id{1};
static constexpr std::string_view machine_name = "MACHINE1";
static constexpr MachineType machine_type = MachineType::LASER;
}
```

### Debugging without hardware with Wokwi ESP32 emulator
## Configuration guide - debugging with Wokwi ESP32 emulator

This is a facultative but very helpful setup to shorten the development workflow.

- Install ESP-IDF extension, Wokwi extension with evaluation license
- Install ESP-IDF extension, Wokwi extension with community evaluation license

> Make sure ESP-IDF platform is esp32s2
> Make sure ESP-IDF platform is esp32s2 (used by wokwi Platformio environment)
- Build PlatformIO wokwi project, and start simulation with command <code>Wokwi: Start Simulator</code>, you shall see the program running:

Expand All @@ -65,60 +116,3 @@ This is a facultative but very helpful setup to shorten the development workflow
- You can then run the application, setup breakpoints, inspect variables from the Wokwi debugger:

![image](https://github.com/fablab-bergamo/rfid-arduino/assets/6236243/55f926b5-eec8-49d9-b217-628e07f7e3b8)

## Configuration steps

- See <code>pins.h</code> to set the GPIO pins for LCD parallel interface, relay, buzzer and RFID reader SPI interface.
- See <code>conf.h</code> to configure LCD dimensions, timeouts, debug logs and some behaviours (e.g. time before to power off the machine)
- See <code>secrets.h</code> to configure network SSID/Password, MQTT topics/credentials/server, whitelisted RFID tags

Key settings:

> Configure MQTT broker IP and credentials. A sample broker file is available in the rfid-backend project.
```c++
namespace secrets::mqtt
{
static constexpr std::string_view client = "BOARD"; /* Name of with MQTT client */
static constexpr std::string_view user = "user"; /* Change with MQTT user */
static constexpr std::string_view password = "password"; /* Change with MQTT password */
static constexpr std::string_view server = "192.168.1.1"; /* IP of MQTT broker*/
static constexpr std::string_view topic = "/machine"; /* Initial part of the topic, machine ID will be added */
static constexpr std::string_view response_topic = "/reply"; /* Server reply (sub-topic of the full machine topic) */
} // namespace secrets::mqtt
```

> To add a white-listed RFID card, edit the tuples list <code>whitelist</code>. These RFID tags will be always authorized, even without server connection.
```c++
static constexpr WhiteList whitelist /* List of RFID tags whitelisted, regardless of connection */
{
std::make_tuple(0xAABBCCD1, FabUser::UserLevel::FABLAB_ADMIN, "ABCDEFG"),
...
std::make_tuple(0xAABBCCDA, FabUser::UserLevel::FABLAB_USER, "USER1")
};
```
> To map the switch Shelly control MQTT topic, edit the <code>machine_topic</code> under <code>secrets::machine</code>
```c++
namespace secrets::machine
{
...
static constexpr std::string_view machine_topic = "shelly/command/switch:0";
...
} // namespace secrets::machine
```

## DEMO - Testing in the browser

- Download latest <code>esp32-wokwi.zip</code> file from Github Actions / platformio.yml / Artifacts
- Extract <code>esp32-wokwi.bin</code> file from artifact ZIP
- Open WOKWI Circuit https://wokwi.com/projects/363448917434192897
- In code editor, press F1 > Upload firmware ... and pick the <code>esp32-wokwi.bin</code> file

![image](https://github.com/fablab-bergamo/rfid-arduino/assets/6236243/5c41092e-f8bf-451a-95ec-8dc6d7e07824)

- When the preprocessor constant <code>WOKWI_SIMULATION=true</code> is set:
- RFID chip is replaced with a mockup simulating random RFID tags from whitelist from time to time (<code>MockRFIDWrapper</code> class).
- A simple MQTT broker (<code>MockMQTTBroker</code> class) is run in a separate thread on esp32s2

0 comments on commit 6d1ef93

Please sign in to comment.