mm::capture Namespace Reference

Classes
struct	Datagram
	The header of one datagram in a frame, without its data. More...
struct	EtherCatFrame
	One EtherCAT frame. More...
struct	KindSummary
	The counts for one kind of frame. More...
class	PcapWriter
	Writes records to a pcap file as they arrive. More...
struct	Record
	One captured frame. More...
struct	Summary
	The summary of one capture. More...

Typedefs
using	FrameSink = std::function< void(int64_t timestampNs, std::span< const uint8_t > bytes)>
	Called for every frame, with nanoseconds since the Unix epoch and the frame from the Ethernet header on. Called on the capturing thread, in time order.

Functions
std::expected< void, std::string >	captureFrames (const std::string &adapter, std::chrono::milliseconds duration, const FrameSink &sink)
	Captures the EtherCAT frames that leave or enter adapter for duration.
bool	isLogicalCommand (uint8_t command)
	Whether command addresses the process image: LRD, LWR or LRW.
bool	isPositionCountedUp (uint8_t command)
	Whether every slave counts command's position up as the frame passes.
std::optional< EtherCatFrame >	parseEtherCatFrame (std::span< const uint8_t > bytes)
	Reads one Ethernet frame that carries EtherCAT datagrams.
std::expected< std::vector< Record >, std::string >	parsePcap (std::span< const uint8_t > bytes)
	Reads every record of a pcap file held in memory.
std::expected< std::vector< Record >, std::string >	readPcap (const std::filesystem::path &path)
	Reads every record of a pcap file into memory. See parsePcap for what is accepted.
Summary	summarise (std::span< const Record > records)
	Summarises records, which must be in time order.
void	to_json (nlohmann::json &j, const Summary &s)
	Serialises a summary, camelCase keys, times in microseconds.

Variables
constexpr uint16_t	kEtherCatEtherType = 0x88A4
	The Ethernet type of an EtherCAT frame.

Typedef Documentation

FrameSink

using mm::capture::FrameSink = typedef std::function<void(int64_t timestampNs, std::span<const uint8_t> bytes)>

Called for every frame, with nanoseconds since the Unix epoch and the frame from the Ethernet header on. Called on the capturing thread, in time order.

Function Documentation

captureFrames()

std::expected< void, std::string > mm::capture::captureFrames	(	const std::string &	adapter,
		std::chrono::milliseconds	duration,
		const FrameSink &	sink
	)

Captures the EtherCAT frames that leave or enter adapter for duration.

Every frame is handed to sink. A frame the master sends and the same frame on its way back are two calls, and the frame tells which it is. Returns when the time is up, or an error when the adapter cannot be opened, which on Linux is a missing CAP_NET_RAW or a wrong name.

isLogicalCommand()

bool mm::capture::isLogicalCommand

(

uint8_t

command

)

Whether command addresses the process image: LRD, LWR or LRW.

The cyclic frame of the RT loop is the one whose first datagram is logical. Everything else is the control plane: mailbox and register reads and writes.

isPositionCountedUp()

bool mm::capture::isPositionCountedUp

(

uint8_t

command

)

Whether every slave counts command's position up as the frame passes.

Auto-increment and broadcast commands come back with another position than they went out with, so a match of a return to its send leaves the position out for them.

parseEtherCatFrame()

std::optional< EtherCatFrame > mm::capture::parseEtherCatFrame

(

std::span< const uint8_t >

bytes

)

Reads one Ethernet frame that carries EtherCAT datagrams.

Parameters

bytes

The frame from the Ethernet header on, without a frame check sequence.

Returns

The frame, or nullopt when it is not an EtherCAT frame of type 1 (EtherCAT command), or its datagrams do not fit its length.

parsePcap()

std::expected< std::vector< Record >, std::string > mm::capture::parsePcap

(

std::span< const uint8_t >

bytes

)

Reads every record of a pcap file held in memory.

Accepts microsecond and nanosecond timestamps and both byte orders, which is what tcpdump and Wireshark write. Only Ethernet captures are accepted, because the frame parser starts at the Ethernet header.

readPcap()

std::expected< std::vector< Record >, std::string > mm::capture::readPcap

(

const std::filesystem::path &

path

)

Reads every record of a pcap file into memory. See parsePcap for what is accepted.

summarise()

Summary mm::capture::summarise

(

std::span< const Record >

records

)

Summarises records, which must be in time order.

to_json()

void mm::capture::to_json	(	nlohmann::json &	j,
		const Summary &	s
	)

Serialises a summary, camelCase keys, times in microseconds.

Variable Documentation

kEtherCatEtherType

constexpr uint16_t mm::capture::kEtherCatEtherType = 0x88A4

inlineconstexpr

The Ethernet type of an EtherCAT frame.