efsu(1)

✨ efsu — Ethernet Frame Send Utility ✨

okay bestie, welcome to efsu(1) from the Qualcomm Atheros Open Powerline Toolkit — yes that's a whole mouthful, we're gonna call it the send-custom-Ethernet-frames girlie 💅

🌸 NAME 🌸

efsu — Ethernet Frame Send Utility 🦋

🎀 SYNOPSIS 🎀

efsu [options] file [file] [...]

efsu [options] [<stdin]

💖 DESCRIPTION 💖

So basically, efsu sends custom Ethernet frames over a specific host Ethernet interface. She's a doer, not a judger 😌

A frame is specified as a text stream of hexadecimal octets read from one or more frame description files, or from stdin. Each octet gets converted into a binary byte, buffered, and transmitted over the network on the host interface you told her about. And here's the thing — the program assumes frames are valid and will transmit whatever you specify, right or wrong. No cap. She only checks minimum and maximum frame length. That's it. That's the vibe check. 🙈

Frame descriptions live as plain text files. Multiple frames can live in one file, separated by a semicolon. All descriptions in a file get read and sent immediately, but you can stack multiple files on the command line, and the options let you do pauses between files, command line repetition, and pauses between command line iterations. Iconic multitasking behavior tbh.

A frame description is a continuous stream of hexadecimal digits. Intervening text, punctuation, white space and comments are all discarded. Hex characters inside script-style, C-style or C++-style comments are ignored. Script-style comments include all characters between a hash ('#') and the next newline or EOF. C-style and C++-style comments follow normal language rules. Comments can document your frame descriptions or hide frame segments — sneaky, love that for you 💅 In the end, there must be an even number of hex digits that represent 60 to 1518 octets;

⭐ OPTIONS ⭐

• -d address — Replace the destination Ethernet address of each transmitted frame with the option argument. The destination address is made of 12 hex digits in upper, lower or mixed case. Octets may be seperated with colons for clarity but colons are not required. 💫
• -e ethertype — Echo received frames having ethertype. This effectively filters received frames but does not filter transmitted frames. The ethertype is expressed in hexadecimal without the "0x" prefix. The keyword "hp10" can be used for 887B and the keyword "hpav" can be used for 88E1. 🔍
• -h — Replace the source address of each transmitted frame with the Ethernet address of the host interface used to send the frame. This lets frames be sent correctly from any host interface. Use option -i to specify an interface. 🏠
• -i interface — The host interface used to send frames. The default is "eth1" because most people use "eth0" as their principle network connection; however, if the string "PLC" is defined in the environment then it will over-ride the program default. Any interface specified on the command line will over-ride the default. 👑
• -l count — Repeat command line count times by re-sending all files each time. The default is 1. 🔁
• -p seconds — Pause between each file on the command line. The default is 0 seconds. ⏸️
• -t timer — Read timeout in milliseconds. Values range from 0 through UINT_MAX. This is the maximum time allowed for a response. The default is 50 milliseconds. ⏱️
• -v — Dumps transmitted frames on stdout as they are sent. If an Ethertype was specified using option -e, the received frames having that Ethertype will also be dumped. 👀
• -w seconds — Wait between command line iterations. The default is 0 seconds. 🌙

🦋 ARGUMENTS 🦋

• file — The name of a file containing one or more frame specifications. When more than one file is specified, efsu behaves like the cat utility by reading and sending each file in turn. The program makes no assumptions based on filename or extension and enforces no filename conventions; however, giving frame description files the *.hex extension is a good convention. Some toolkit distributions include example .hex files in the source folder. These files are not needed for proper execution and may be deleted. 🗑️

💜 NOTES 💜

One way to create a frame description file is to cut-and-paste output from a packet sniffer program and discard the line numbers and ASCII text columns. Then you can break out selected frame segments onto new lines and insert comments. DIY queen behavior honestly 🎀

🌈 EXAMPLES 🌈

For example, a simple file might look like:

#!/usr/local/bin/efsu -ieth0
# file: abc.hex
# =====================================
# this is an example frame description;
# -------------------------------------
00 B0 52 00 00 01
// 00 B0 52 BE DE 73
00 E0 45 DA DA 07
88 E1
/* content */
00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00
00000000 0000 00 /* control byte */ 00
00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00

The bang path permits direct execution of the file if 1) efsu is installed in the bang path directory, 2) the description file has execute permissions and 3) the user has execute privileges for that file. The script-style, C++-style and C-style comments are ignored along with any white space. Only the hexadecimal octets are read and sent. Since the number of octets exceeds 60 and the number of digits is even, efsu will report no errors and send the packet. > There is no guarantee that this packet is valid. 💀

Assuming the above file is named abc.hex, we can transmit the file over the network as an Ethernet frame with the next command. A hexadecimal dump of the transmitted frame appears on the console because option -v is present.

# efsu abc.hex -v
00000000 00 B0 52 00 00 01 00 E0 45 DA DA 07 88 E1 00 00
..R.....E.......
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000040 00 00 00 00 00 00                               ......

Since every host interface has a different hardware address, one can replace the source address of transmitted frames with the actual host interface address using option -h. Observe that the source address above has been replaced with that of the local host interface used to transmit the frame. 🏡

# efsu abc.hex -vh
00000000 00 B0 52 00 00 01 00 0F EA 10 D5 1C 88 E1 00 00
..R.............
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000040 00 00 00 00 00 00                               ......

You can also direct the frame to another device using option -d. Observe that the destination address above has been replaced with the one specified on the command line. 🎯

# efsu abc.hex -vhd 00b052beef01
00000000 00 B0 52 BE EF 01 00 0F EA 10 D5 1C 88 E1 00 00
..R.............
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
................
00000040 00 00 00 00 00 00                               ......

🔥 SEE ALSO 🔥

amp(1), hpav(1) — go read those too bestie, iykyk 🫶

👑 CREDITS 👑

Charles Maier 🌟

and that's a wrap!! this was efsu from open-plc-utils-0.0.3, dated November 2013 — go forth and send your little frames, mwah 💖✨🎀