Skip to content

Latest commit

 

History

History
156 lines (135 loc) · 8.85 KB

configuration.md

File metadata and controls

156 lines (135 loc) · 8.85 KB

Documentation index

Configuration

PJON uses predefined constants, setters and getters to support features and constraints configuration.

Buffers configuration

Before instantiating PJON it is possible to define the length of its buffers. Predefining PJON_MAX_PACKETS and PJON_PACKET_MAX_LENGTH it is possible to configure this constraints to reach the project memory requirements. Obviously, the less memory is dedicated to buffers, the more memory can be used for something else:

#define PJON_MAX_PACKETS 1
#define PJON_PACKET_MAX_LENGTH 20
#include <PJON.h>
/* PJON can store up to 1 packet of up to
   20 characters - packet overhead
   (from 5 to 22 bytes depending by configuration) */

Data link configuration

PJON is instantiated passing a strategy template parameter:

  PJON<SoftwareBitBang> bus;

In the example above the PJON object is instantiated passing SoftwareBitBang strategy. Strategies are classes abstracting the data link layer, making PJON easy to be used on different media. It is possible to instantiate more than one PJON object using different strategies in the same program:

  PJON<SoftwareBitBang> wiredBus;
  PJON<EthernetTCP>     tcpBus;
Strategy Physical layer Protocol Pins needed
SoftwareBitBang Electrical impulses over conductive element PJDL 1 or 2
AnalogSampling Light pulses over air or optic fiber PJDLS 1 or 2
EthernetTCP Electrical/radio impulses over wire/air TCP Ethernet port
LocalUDP Electrical/radio impulses over wire/air UDP Ethernet port
GlobalUDP Electrical/radio impulses over wire/air UDP Ethernet port
DualUDP Electrical/radio impulses over wire/air UDP Ethernet port
OverSampling Electrical/radio impulses over wire/air PJDLR 1 or 2
ThroughSerial Electrical/radio impulses over wire/air TSDL 1 or 2
ThroughSerialAsync Electrical/radio impulses over wire/air TSDL 1 or 2
ThroughLoRa Radio impulses over air LoRa 3 or 4
ESPNOW Radio impulses over air ESPNOW WiFi link
Any Virtual inheritance, any of the above Any of the above Any of the above

By default all strategies are included except ThroughLoRa and ESPNOW. To reduce memory footprint add for example #define PJON_INCLUDE_SWBB before PJON inclusion to include only SoftwareBitBang strategy. More than one strategy related constant can defined in the same program if that is required.

Supported definitions:

  • PJON_INCLUDE_SWBB includes SoftwareBitBang
  • PJON_INCLUDE_AS includes AnalogSampling
  • PJON_INCLUDE_ETCP includes EthernetTCP
  • PJON_INCLUDE_GUDP includes GlobalUDP
  • PJON_INCLUDE_LUDP includes LocalUDP
  • PJON_INCLUDE_OS includes OverSampling
  • PJON_INCLUDE_TS includes ThroughSerial
  • PJON_INCLUDE_TSA includes ThroughSerialAsync
  • PJON_INCLUDE_TL includes ThroughLoRa
  • PJON_INCLUDE_EN includes ESPNOW
  • PJON_INCLUDE_ANY includes Any
  • PJON_INCLUDE_NONE no strategy file included

Before using ThroughLoRa be sure to have arduino-LoRa source available and to have defined the PJON_INCLUDE_TL constant before including PJON.h.

Before using ESPNOW be sure to have installed the required tools as described here and to have defined the PJON_INCLUDE_EN constant before including PJON.h.

Network mode

The network mode can be changed with set_shared_network during runtime, for example moving from local to shared mode:

  bus.set_shared_network(true);

Communication mode

The communication mode can be configured using the set_communication_mode passing PJON_SIMPLEX for simplex or mono-directional mode or PJON_HALF_DUPLEX for half-duplex or bidirectional mode:

  // Run in mono-directional PJON_SIMPLEX mode
  bus.set_communication_mode(PJON_SIMPLEX);
  // Run in bi-directional PJON_HALF_DUPLEX mode
  bus.set_communication_mode(PJON_HALF_DUPLEX);

Router mode

Use set_router to configure the device in router mode, simply receiving all the incoming packets:

  bus.set_router(true);

Sender information

PJON by default includes the sender's information in the packet, If required include_sender_info can be used as shown below to avoid including sender's information:

  bus.include_sender_info(false);

CRC configuration

With set_crc_32 CRC32 can be forced on each packet sent to higher reliability:

  bus.set_crc_32(true);

Packet handling

If manual packet handling is required, packet automatic deletion can be avoided using set_packet_auto_deletion as shown below:

  bus.set_packet_auto_deletion(false);

Acknowledgement

The synchronous acknowledgement is by default enabled but can be disabled if required:

  bus.set_synchronous_acknowledge(false);

If the asynchronous acknowledgement feature is required you need to define the PJON_INCLUDE_ASYNC_ACK as following. The use of a constant has been chosen to save more than 1kB on sketches where this feature is not used (the packet id is used by the asynchronous acknowledgement process, so if necessary, play with that responsibly):

#define PJON_INCLUDE_ASYNC_ACK true
// Max number of old packet ids stored to avoid duplication
#define PJON_MAX_RECENT_PACKET_IDS 10  // by default 10
// If packet duplication occurs, higher PJON_MAX_RECENT_PACKET_IDS
#include <PJON.h>

Use set_asynchronous_acknowledge to enable the asynchronous acknowledgement:

  // Enable async ack
  bus.set_asynchronous_acknowledge(true);

See the AsyncAck example to see more in detail how the asynchronous acknowledgement can be used.

Packet identification

If packet duplication avoidance is required it is possible to add a 2 bytes packet identifier to guarantee uniqueness. define the PJON_INCLUDE_PACKET_ID as following. The use of a constant has been chosen to save more than 1kB on sketches where this feature is not used:

#define PJON_INCLUDE_PACKET_ID true
// Max number of old packet ids stored to avoid duplication
#define PJON_MAX_RECENT_PACKET_IDS 10  // by default 10
// If packet duplication occurs, higher PJON_MAX_RECENT_PACKET_IDS
#include <PJON.h>

Use set_packet_id to enable the packet identification feature:

  bus.set_packet_id(true);

See the UsePacketId example to see more in detail how the packet id can be used.

Network service identification

Configure the instance to include a network service identifier in the packet. Ports from 0 to 8000 are reserved to known network services which index is present in the known network services list, ports from 8001 to 65535 are free for custom use cases:

  bus.include_port(false);      // Avoid port inclusion (default)  
  bus.include_port(true, 8001); // Include custom port

See the PortsUseExample example to see more in detail how the port feature can be used.