Skip to content

Latest commit

 

History

History
 
 

strategies

README.md

What is a Strategy

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>

How the strategy is implemented

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.

How to implement a 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);