mxbranson · mxbranson · Jun 26, 2020 · Jun 26, 2020 · Jun 26, 2020 · Jun 28, 2020
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,6 +1,6 @@
-All the software included in this project is experimental and it is distributed "AS IS" without any warranty, use it at your own risk. All specifications, all related software implementations and documentation released as a part of this repository are and will always remain free for personal, educational, experimental and commercial purposes.
+All the software included in this project is experimental and it is distributed "AS IS" without any warranty, use it at your own risk.
 
-Giovanni Blu Mitolo (gioscarab@gmail.com) Copyright 2010-2020
+Giovanni Blu Mitolo (gioscarab@gmail.com) Copyright 2010-2025
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 

diff --git a/README.md b/README.md
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,7 +4,7 @@ PJON is still in experimental phase and it distributed "AS IS" without any warra
 The security of a system that uses PJON for communication mostly depends on the vulnerabilities exposed by the hardware and by the physical layer used. Consider that **only air-gapped wired local buses are undoubtely secure**. When connecting a local bus to the internet using [ESPNOW](/src/strategies/ESPNOW), [EthernetTCP](/src/strategies/EthernetTCP) or [LocalUDP](/src/strategies/LocalUDP), [GlobalUDP](/src/strategies/GlobalUDP) or [DualUDP](/src/strategies/DualUDP), all connected devices must be considered potentially compromised. It should be considered a good practice not to connect to the internet systems that may cause damage (fire, flood, data-leak) if hacked.
 
 ### Safety warning
-When installing or maintaining a PJON network, extreme care must be taken to avoid any danger. If devices are connected to AC power you are exposed to a high chance of being electrocuted if hardware is not installed carefully and properly. If you are not experienced enough ask the support of a skilled technician and consider that many countries prohibit uncertified installations. When a [SoftwareBitBang](/src/strategies/SoftwareBitBang) bus is installed [interference mitigation](https://github.com/gioblu/PJON/wiki/Mitigate-interference) and [protective circuitry](https://github.com/gioblu/PJON/wiki/Protective-circuitry) guidelines must be followed. When working with an [AnalogSampling](/src/strategies/AnalogSampling) LED or laser based setup safety glasses must be worn and transceivers must be operated cautiously to avoid potential eye injuries. Before any practical test or a hardware purchase for a wireless [OverSampling](/src/strategies/OverSampling), [ThroughSerial](/src/strategies/ThroughSerial) or [ThroughLoRa](/src/strategies/ThroughLoRa) radio setup, compliance with government requirements and regulations must be ensured.
+When testing PJON, take extreme care to avoid any danger. The implementation is experimental and may not behave as expected; use it at your own risk. If devices are connected to AC power, you face a high risk of electrocution unless the hardware is installed carefully and correctly. If you lack sufficient experience, seek assistance from a qualified technician, and be aware that many countries prohibit uncertified installations. When testing a [SoftwareBitBang](/src/strategies/SoftwareBitBang) bus follow [interference-mitigation](https://github.com/gioblu/PJON/wiki/Mitigate-interference) and [protective-circuitry](https://github.com/gioblu/PJON/wiki/Protective-circuitry) guidelines. When experimenting with an AnalogSampling setup, wear safety glasses and operate transceivers cautiously to prevent eye injuries. Before testing [OverSampling](/src/strategies/OverSampling), [ThroughSerial](/src/strategies/ThroughSerial) or [ThroughLoRa](/src/strategies/ThroughLoRa) radio communication, ensure that the frequency, power, and hardware comply with local regulations. When connecting a local bus to the Internet, treat all devices as potentially compromised, manipulated, or remotely actuated against your will. As a best practice, avoid connecting to the internet systems that could cause damage (fire, flood, data leakage) if hacked.
 
 ### Reporting a Vulnerability
 If you discover a vulnerability in the specification or in the implementation please report it as soon as possible opening an [issue](https://github.com/gioblu/PJON/issues). If you have developed a fix, feel free to open a [pull request](https://github.com/gioblu/PJON/pulls).
diff --git a/devices/sensors/LEDAR/README.md b/devices/sensors/LEDAR/README.md
@@ -18,7 +18,7 @@ Many LEDARs can be connected to the same [SoftwareBitBang](/src/strategies/Softw
 
 Its detection method is based on two interesting characteristics of LEDs:
 - If hit by light, LEDs produce a tiny amount of electricity, thanks to the photo-electric effect
-- LEDs used as detectors are generally more sensitive to the frequency they emit if used as emitters, making a couple of identical LEDs generally used for lighting, in two extremely efficient wireless transceivers that can be used for reflectometry or also for wireless communication using the [AnalogSampling](/src/strategies/AnalogSampling/README.md) strategy
+- LEDs used as detectors are generally more sensitive to the frequency they emit if used as emitters, so a couple of identical LEDs generally used for lighting can be used successfully as wireless transceivers for reflectometry or optical wireless communication using the [AnalogSampling](/src/strategies/AnalogSampling/README.md) strategy
 
 Its sampling method is based on two different samples:
 - Background noise or ambient light sample `B`
@@ -79,6 +79,6 @@ The case is made by two elements and it has been printed using a customized Prus
 
 Once crafted, ATtiny85 has to be flashed with the [LEDAR](software/LEDAR/LEDAR.ino) sketch using an ISP programmer, see [ATtiny85 interfacing](https://github.com/gioblu/PJON/wiki/ATtiny-interfacing)
 
-LEDAR has been engineered with the strong feeling that, in the future, "smart houses" will not necessarily host a multitude of inefficient and convoluted embedded real-time operative systems, in whatever "thing", consuming a lot of power running Ethernet over WiFi and exposing vulnerabilities also out of the physical boundaries of houses. Otherwise, more probably, will host many dedicated microcontrollers connected to a wired, common, open-source, lightweight and less power consuming communication bus, unhackable without direct physical access to its wiring.
+LEDAR has been engineered with the strong feeling that, in the future, "smart houses" will not necessarily host a multitude of inefficient embedded real-time operating systems in whatever "thing" while exposing vulnerabilities out of the physical boundaries of houses. Otherwise, more probably, will host many simple, less power-hungy microcontrollers, connected to a wired communication bus, unhackable without direct physical access to its wiring.
 
 LEDAR should be considered as a general "guideline" on how PJON compatible devices can be published and shared with other PJON users through the [devices](../../README.md) directory. Feel free to make a pull request proposing a new device you have engineered.   
diff --git a/documentation/README.md b/documentation/README.md
@@ -1,13 +1,21 @@
 
 ### Documentation index
 - [Addressing](/documentation/addressing.md)
+  - [`set_id`](/documentation/addressing.md#local-mode) [`device_id`](/documentation/addressing.md#local-mode) [`get_bus_id`](/documentation/addressing.md#shared-mode) [`set_bus_id`](/documentation/addressing.md#shared-mode) [`get_mac`](/documentation/addressing.md#get-or-set-hardware-identifier) [`set_mac`](/documentation/addressing.md#get-or-set-hardware-identifier)
 - [Configuration](/documentation/configuration.md)
+  - [`set_communication_mode`](/documentation/configuration.md#communication-mode) [`set_shared_network`](/documentation/configuration.md#network-mode) [`set_router`](/documentation/configuration.md#router-mode) [`include_sender_info`](/documentation/configuration.md#sender-information) [`set_crc_32`](/documentation/configuration.md#crc-configuration) [`set_packet_auto_deletion`](/documentation/configuration.md#packet-handling) [`set_acknowledge`](/documentation/configuration.md#acknowledgement) [`set_packet_id`](/documentation/configuration.md#packet-identification) [`include_port`](/documentation/configuration.md#network-service-identification) [`include_mac`](/documentation/configuration.md#hardware-identification)
 - [Data reception](/documentation/data-reception.md)
+  - [`set_receiver`](/documentation/data-reception.md#data-reception) [`receive`](/documentation/data-reception.md#data-reception)
+- [Data structures](/documentation/data-structures.md)
+  - [`PJON_Endpoint`](/documentation/data-structures.md#pjon_endpoint) [`PJON_Packet_Info`](/documentation/data-structures.md#pjon_packet_info)
 - [Data transmission](/documentation/data-transmission.md)
+  - [`begin`](/documentation/data-transmission.md#begin) [`reply`](/documentation/data-transmission.md#reply) [`reply_blocking`](/documentation/data-transmission.md#reply_blocking) [`send`](/documentation/data-transmission.md#send) [`send_packet`](/documentation/data-transmission.md#send_packet) [`send_packet_blocking`](/documentation/data-transmission.md#send_packet_blocking) [`send_repeatedly`](/documentation/data-transmission.md#send_repeatedly) [`reply`](/documentation/data-transmission.md#reply) [`reply_blocking`](/documentation/data-transmission.md#reply_blocking) [`forward`](/documentation/data-transmission.md#forward) [`forward_blocking`](/documentation/data-transmission.md#forward_blocking)
 - [Error handling](/documentation/error-handling.md)
-- [IO setup](/documentation/io-setup.md)
+  - [`set_error`](/documentation/error-handling.md#error-handling)
 - [Routing](/documentation/routing.md)
-
+   - [`PJONSimpleSwitch`](/documentation/routing.md#simpleswitch) [`PJONSwitch`](/documentation/routing.md#switch) [`PJONRouter`](/documentation/routing.md#router) [`PJONDynamicRouter`](/documentation/routing.md#dynamicrouter) [`PJONInteractiveRouter`](/documentation/routing.md#interactiverouter)
+- [IO setup](/documentation/io-setup.md)
+   - [`strategy`](/documentation/io-setup.md#io-setup)
 ---
 
 ## Documentation

diff --git a/documentation/addressing.md b/documentation/addressing.md
@@ -1,27 +1,36 @@
 
 ### Documentation index
 - **[Addressing](/documentation/addressing.md)**
+  - [`set_id`](/documentation/addressing.md#local-mode) [`device_id`](/documentation/addressing.md#local-mode) [`get_bus_id`](/documentation/addressing.md#shared-mode) [`set_bus_id`](/documentation/addressing.md#shared-mode) [`get_mac`](/documentation/addressing.md#get-or-set-hardware-identifier) [`set_mac`](/documentation/addressing.md#get-or-set-hardware-identifier)
 - [Configuration](/documentation/configuration.md)
+  - [`set_communication_mode`](/documentation/configuration.md#communication-mode) [`set_shared_network`](/documentation/configuration.md#network-mode) [`set_router`](/documentation/configuration.md#router-mode) [`include_sender_info`](/documentation/configuration.md#sender-information) [`set_crc_32`](/documentation/configuration.md#crc-configuration) [`set_packet_auto_deletion`](/documentation/configuration.md#packet-handling) [`set_acknowledge`](/documentation/configuration.md#acknowledgement) [`set_packet_id`](/documentation/configuration.md#packet-identification) [`include_port`](/documentation/configuration.md#network-service-identification) [`include_mac`](/documentation/configuration.md#hardware-identification)
 - [Data reception](/documentation/data-reception.md)
+  - [`set_receiver`](/documentation/data-reception.md#data-reception) [`receive`](/documentation/data-reception.md#data-reception)
+- [Data structures](/documentation/data-structures.md)
+  - [`PJON_Endpoint`](/documentation/data-structures.md#pjon_endpoint) [`PJON_Packet_Info`](/documentation/data-structures.md#pjon_packet_info)
 - [Data transmission](/documentation/data-transmission.md)
+  - [`begin`](/documentation/data-transmission.md#begin) [`reply`](/documentation/data-transmission.md#reply) [`reply_blocking`](/documentation/data-transmission.md#reply_blocking) [`send`](/documentation/data-transmission.md#send) [`send_packet`](/documentation/data-transmission.md#send_packet) [`send_packet_blocking`](/documentation/data-transmission.md#send_packet_blocking) [`send_repeatedly`](/documentation/data-transmission.md#send_repeatedly) [`reply`](/documentation/data-transmission.md#reply) [`reply_blocking`](/documentation/data-transmission.md#reply_blocking) [`forward`](/documentation/data-transmission.md#forward) [`forward_blocking`](/documentation/data-transmission.md#forward_blocking)
 - [Error handling](/documentation/error-handling.md)
-- [IO setup](/documentation/io-setup.md)
+  - [`set_error`](/documentation/error-handling.md#error-handling)
 - [Routing](/documentation/routing.md)
+  - [`PJONSimpleSwitch`](/documentation/routing.md#simpleswitch) [`PJONSwitch`](/documentation/routing.md#switch) [`PJONRouter`](/documentation/routing.md#router) [`PJONDynamicRouter`](/documentation/routing.md#dynamicrouter) [`PJONInteractiveRouter`](/documentation/routing.md#interactiverouter)
+- [IO setup](/documentation/io-setup.md)
+   - [`strategy`](/documentation/io-setup.md#io-setup)
 
 ---
 
 ## Addressing
-PJON objects can operate in local or shared mode. The PJON protocol v3.2 in [local](/specification/PJON-protocol-specification-v3.2.md#local-mode) mode supports connectivity for up to 254 devices using a 8bits device identifier, in [shared](/specification/PJON-protocol-specification-v3.2.md#shared-mode) mode supports connectivity for up to 4.294.967.295 buses (groups of devices) and up to 1.090.921.692.930 devices using a 32bits bus identifier and a 8bits device identifier.
+PJON objects can operate in local or shared mode. The PJON protocol v4.0 in [local](/specification/PJON-protocol-specification-v4.0.md#local-mode) mode supports connectivity for up to 254 devices using a 8bits device identifier, in [shared](/specification/PJON-protocol-specification-v4.0.md#shared-mode) mode supports connectivity for up to 4.294.967.295 buses (groups of devices) and up to 1.090.921.692.930 devices using a 32bits bus identifier and a 8bits device identifier.
 
 ### Local mode
 
-The simples way to instantiate PJON in local mode is the following:
+The simplest way to instantiate PJON in local mode is as follows:
 ```cpp  
-  PJON<SoftwareBitBang> bus;
+  PJONSoftwareBitBang bus;
 ```
 When the object is instantiated without passing parameters it operates in local mode and the device identifier is set to 255 or `PJON_NOT_ASSIGNED`. PJON objects can be instantiated passing the device identifier:
 ```cpp
-  PJON<SoftwareBitBang> bus(44);
+  PJONSoftwareBitBang bus(44);
 ```
 `bus` receives packets for device identifier 44 and ignores all others.
 
@@ -39,21 +48,60 @@ The device identifier of an object can be read after instantiation using `device
 ```cpp  
   uint8_t id = bus.device_id(); // Get device id
 ```
-`device_id` returns 255 or `PJON_NOT_ASSIGNED` if the instance is initialised without configuring its device identifier.
+`device_id` returns `PJON_NOT_ASSIGNED` or 255 if the instance is initialised without configuring its device identifier.
 
 ### Shared mode
 
-if the medium used is private and not accessible from the outside world (wired network in home, business, industry) any  bus indexing scheme can be used without worrying about bus id collision; if instead the network uses a shared medium, such as commonly used radio frequencies like LoRa, it is strongly suggested to request a unique PJON bus id [here](http://www.pjon.org/get-bus-id.php) to avoid collisions.
+if the medium used is private and not accessible from the outside world (wired network in home, business, industry), bus ids can be used arbitrarily without any risk of collision; if instead the network uses a shared medium, for example on unlicensed radio frequencies with [ThroughLoRa](/src/strategies/ThroughLoRa).
 
 Instantiation in shared mode:
 ```cpp
 uint8_t bus_id[4] = {1, 2, 3, 4};
-PJON<SoftwareBitBang> bus(bus_id, 44);
+PJONSoftwareBitBang bus(bus_id, 44);
 // Device id 44, bus id 1.2.3.4 in shared mode
 ```
 ### Get or set bus identifier
 
-The bus id can be read and set after initialisation using `bus_id`:
+Use `get_bus_id` to get a pointer to the bus id used by the instance:
+```cpp  
+  uint8_t bus_id[4];
+  memcpy(bus_id, bus.get_bus_id(bus_id), 4); // Copy bus id in bus_id
+```
+
+The bus id can be set after initialisation using `set_bus_id`:
+```cpp  
+  uint8_t bus_id[4] = {0, 0, 0, 1};
+  bus.set_bus_id(bus_id); // Set bus id
+```
+
+### Hardware identifier
+
+PJON can optionally operate using the MAC address of the device:
+```cpp
+// Include MAC address feature
+#define PJON_INCLUDE_MAC
+
+// MAC address of the device
+uint8_t mac[6] = {1, 2, 3, 4, 5, 6};
+
+PJONSoftwareBitBang bus(mac);
+// Local mode, device id PJON_NOT_ASSIGNED
+```
+This instantiation sets the MAC address, the device id set to `PJON_NOT_ASSIGNED` or 255 but can be changed afterwards as required. Packets containing a recipient's MAC address that is not equal to the one configured are discarded. PJON can operate in both local and shared mode while including MAC addresses. The feature can be disabled using `include_mac`:
+
+```cpp
+bus.include_mac(false);
+```
+### Get or set hardware identifier
+
+Use `get_mac` to get a pointer to the mac address used by the instance:
+```cpp  
+  uint8_t mac[6];
+  memcpy(mac, bus.get_mac(mac), 6); // Copy mac in variable
+```
+
+The mac address can be set after initialisation using `set_mac`:
 ```cpp  
-  bus.bus_id; // Get or set bus id
+  uint8_t mac[6] = {0, 0, 0, 0, 0, 1};
+  bus.set_mac(mac); // Set mac
 ```