beam.py¶
The beam.py example program uses the Simple NDEF Exchange Protocol (SNEP) to send or receive NDEF messages to or from a peer device, in most cases this will be a smartphone. The name beam is inspired by Android Beam and thus beam.py will be able to receive most content sent through Android Beam. It will not work for data that Android Beam sends with connection handover to Bluetooth or Wi-Fi, this may become a feature in a later version. Despite it’s name, beam.py works not only with Android phones but any NFC enabled phone that implements the NFC Forum Default SNEP Server, such as Blackberry and Windows Phone 8.
$ beam.py [-h|--help] [OPTIONS] {send|recv} [-h] [OPTIONS]
Options¶
-
--loop
,
-l
¶
Repeat the command endlessly, use Control-C to abort.
-
--mode
{t,i}
¶ Restrict the choice of NFC-DEP connection setup role to either
Target
(only listen) orInitiator
(only poll). If this option is not given the dafault is to alternate between both roles with a randomized listen time.
-
--miu
INT
¶ Set a specific value for the LLCP Link MIU. The dafault value is 2175 octets.
-
--lto
INT
¶ Set a specific LLCP Link Timeout value. The default link timeout is 500 milliseconds.
-
--listen-time
INT
¶ Set the time to listen for initialization command from an NFC-DEP Initiator. The default listen time is 250 milliseconds.
-
--no-aggregation
¶
Disable outbound packet aggregation for LLCP, i.e. do not generate LLCP AGF PDUs if multiple packets are waiting to be send. This is mostly to achieve communication with some older/buggy implementations.
-
-q
¶
Do not print log messages except for errors and warnings.
-
-d
MODULE
¶ Output debug messages for MODULE to the log facility. Logs are written to <stderr> unless a log file is set with
-f
. MODULE is a string that corresponds to an nfcpy module or individual file, with dots between path components. For example,-d nfc
enables all nfcpy debug logs,-d nfc.tag
enables debug logs for all tag types, and-d nfc.tag.tt3
enables debug logs only for type 3 tags. This option may be given multiple times to enable debug logs for several modules.
-
-f
LOGFILE
¶ Write debug log messages to <LOGFILE> instead of <stderr>. Info, warning and error logs will still be printed to <stderr> unless
-q
is set to supress info messages on <stderr>.
-
--nolog-symm
¶
When operating in peer mode this option prevents logging of LLCP Symmetry PDUs from the
nfc.llcp.llc
module. Symmetry PDUs are exchanged regularly and quite frequently over an LLCP Link and are logged by default if debug output is enabled for the llcp module.
-
--device
PATH
¶ Use a specific reader or search only for a subset of readers. The syntax for PATH is:
usb[:vendor[:product]]
with optional vendor and product as four digit hexadecimal numbers, likeusb:054c:06c3
would open the first Sony RC-S380 reader andusb:054c
the first Sony reader.usb[:bus[:device]]
with optional bus and device number as three-digit decimal numbers, likeusb:001:023
would specifically mean the usb device with bus number 1 and device id 23 whereasusb:001
would mean to use the first available reader on bus number 1.tty:port:driver
with mandatory port and driver name should be used on Posix systems to open the serial port at device node/dev/tty<port>
and load the driver from modulenfc/dev/<driver>.py
. A typical example would betty:USB0:arygon
for the Arygon APPx/ADRx at/dev/ttyUSB0
.com:port:driver
with mandatory port and driver name should be used on Windows systems to open the serial portCOM<port>
and load thenfc/dev/<driver>.py
driver module.udp[:host][:port]
with optional host name or address and port number will use a fake communication channel over UDP/IP. Either value may be omitted in which case host defaults to ‘localhost’ and port defaults to 54321.
Commands¶
send¶
Send an NDEF message to the peer device. The message depends on the positional argument that follows the send command and additional data.
$ beam.py send [--timeit] {link,text,file,ndef} [-h] [OPTIONS]
-
--timeit
¶
Measure and print the time that was needed to send the message.
send link¶
Send a hyperlink embedded into a smartposter record.
$ beam.py send link URI [TITLE]
-
URI
¶
The resource identifier, for example
http://nfcpy.org
.
-
TITLE
¶
The smartposter title, for example
"nfcpy project home"
.
send text¶
Send plain text embedded into an NDEF Text Record. The default
language identifier en
can be changed with the --lang
flag.
$ beam.py send text TEXT [OPTIONS]
-
TEXT
¶
The text string to send.
-
--lang
STRING
¶ The language code to use when constructing the NDEF Text Record.
send file¶
Send a data file. This will construct a single NDEF record with type
and name set to the file’s mime type and path name, and the payload
containing the file content. Both record type and name can also be
explicitly set with the options -t
and -n
, respectively.
$ beam.py send file FILE [OPTIONS]
-
FILE
¶
The file to send.
-
-n
STRING
¶ Set the record name (identifier).
send ndef¶
Send an NDEF message read from file. The file may contain multiple
messages and if it does, then the strategy to select a specific
message for sending can be specified with the --select STRATEGY
option. For strategies that select a different message per touch
beam.py must be called with the --loop
flag. The strategies
first
, last
and random
select the first, or last, or a
random message from FILE. The strategies next
and cycle
start
with the first message and then count up, the difference is that
next
stops at the last message while cycle
continues with the
first.
$ beam.py send ndef FILE [OPTIONS]
-
FILE
¶
The file from which to read NDEF messages.
-
--select
STRATEGY
¶ The strategy for NDEF message selection, it may be one of
first
,last
,next
,cycle
,random
.
recv¶
Receive an NDEF message from the peer device. The next positional argument determines what is done with the received message.
$ beam.py [OPTIONS] recv {print,save,echo,send} [-h] [OPTIONS]
recv save¶
Save the received message into a file. If the file already exists the message is appended.
$ beam.py recv save FILE
-
FILE
¶
Name of the file to save messages received from the remote peer. If the file exists any new messages are appended.
recv send¶
Receive a message and send back a corresponding message if such is found in the translations file. The translations file must contain an even number of NDEF messages which are sequentially read into inbound/outbound pairs to form a translation table. If the receved message corresponds to any of the translation table inbound messages the corresponding outbound message is then sent back.
$ beam.py [OPTIONS] recv send [-h] TRANSLATIONS
-
TRANSLATIONS
¶
A file with a sequence of NDEF messages.
Examples¶
Get a smartphone to open the nfcpy project page (which in fact just points to the code repository and documentation).
$ beam.py send link http://nfcpy.org "nfcpy project home"
Send the source file beam.py
. On an Android phone this should pop
up the “new tag collected” screen and show that a text/x-python
media type has been received.
$ beam.py send file beam.py
The file beam.py
is about 11 KB and may take some time to
transfer, depending on the phone hardware and software. With a Google
Nexus 10 it takes as little as 500 milliseconds while a Nexus 4 won’t
do it under 2.5 seconds.
$ beam.py send --timeit file beam.py
Receive a single NDEF message from the peer device and save it to message.ndef (note that if message.ndef exists the received data will be appended):
$ beam.py recv save message.ndef
With the --loop
option it gets easy to collect messages into
a single file.
$ beam.py --loop recv save collected.ndef
A file that contains a sequence of request/response message pairs can be used to send a specific response message whenever the associated request message was received.
$ echo -n "this is a request message" > request.txt
$ ndeftool.py pack -n '' request.txt -o request.ndef
$ echo -n "this is my reponse message" > response.txt
$ ndeftool.py pack -n '' response.txt -o response.ndef
$ cat request.ndef response.ndef > translation.ndef
$ beam.py recv send translation.ndef