A strategy is an abstraction layer used to physically transmit data. Thanks to the strategies PJON can operate transparently on a wide range of media and protocols. Take a look at the strategies video introduction for a brief showcase of their features.
The table below lists the strategies available:
Strategy | Physical layer | Protocol | Inclusion |
---|---|---|---|
AnalogSampling | Light | PJDLS | #include <PJONAnalogSampling.h> |
Any | Virtual inheritance | Any | #include <PJONAny.h> |
DualUDP | Ethernet/WiFi | UDP | #include <PJONDualUDP.h> |
ESPNOW | WiFi | ESPNOW | #include <PJONESPNOW.h> |
EthernetTCP | Ethernet/WiFi | TCP | #include <PJONEthernetTCP.h> |
GlobalUDP | Ethernet/WiFi | UDP | #include <PJONGlobalUDP.h> |
LocalFile | File system | None | #include <PJONLocalFile.h> |
LocalUDP | Ethernet/WiFi | UDP | #include <PJONLocalUDP.h> |
MQTTTranslate | Ethernet/WiFi | MQTT | #include <PJONMQTTTranslate.h> |
OverSampling | Radio | PJDLR | #include <PJONOverSampling.h> |
SoftwareBitBang | Wire | PJDL | #include <PJONSoftwareBitBang.h> |
ThroughLoRa | Radio | LoRa | #include <PJONThroughLora.h> |
ThroughSerial | Wire | TSDL | #include <PJONThroughSerial.h> |
A Strategy
is a class containing a set of methods used to physically send and receive data along with the required getters to handle retransmission and collision:
bool begin(uint8_t did = 0)
Receives an optional parameter of type uint8_t
(when PJON calls begin
it passes its own device id); returns true
if the strategy is correctly initialized. There is no doubt that the strategy should not know about the PJON's device id, although that is practically useful in many cases.
uint32_t back_off(uint8_t attempts)
receives a paramenter of type uint8_t
and returns the suggested delay for a given number of attempts.
bool can_start()
Returns true
if the medium is free for use and false
if the medium is busy.
void handle_collision()
Handles a collision.
uint8_t get_max_attempts()
Returns the maximum number of attempts in case of failed transmission.
uint16_t get_receive_time()
Returns the minimum polling time required to successfully receive a frame.
void send_frame(uint8_t *data, uint16_t length)
Receives a pointer to the data and its length and sends it through the medium. The sending procedure must be blocking.
uint16_t receive_frame(uint8_t *data, uint16_t max_length) { ... };
Receives a pointer where to store received information and an unsigned integer signalling the maximum data length. It should return the number of bytes received or PJON_FAIL
.
void send_response(uint8_t response)
Send a response to the packet's transmitter.
uint16_t receive_response()
Receives a response from the packet's receiver.
// Simple Serial data link layer implementation example
void send_response(uint8_t response) {
Serial.print(response);
};
Above it is demonstrated how simply other communication protocols can be used to define a new custom strategy.
To define a new custom strategy you need to create a new folder named for example YourStrategyName
in the src/strategies
directory and create the necessary file YourStrategyName.h
:
class YourStrategyName {
public:
uint32_t back_off(uint8_t attempts) { };
bool begin(uint8_t did) { };
bool can_start() { };
uint8_t get_max_attempts() { };
uint16_t get_receive_time() { };
uint16_t receive_frame(uint8_t *data, uint16_t max_length) { };
uint16_t receive_response() { };
void send_response(uint8_t response) { };
void send_frame(uint8_t *data, uint16_t length) { };
};
If all is correct it should be possible to instantiate PJON using the new strategy:
PJON<YourStrategyName> bus(44);
// Use PJON as always
Strategy related methods required for configuration can be defined within the strategy. For example the SoftwareBitBang
strategy uses a dedicated setter for the communication pin:
bus.strategy.set_pin(12);