NFC tags

asuka/sdk/nfc reads and writes NFC tags: their NDEF messages (links, texts, data of the app's own), the tags themselves (their IDs and technologies), and raw commands to them. It's what react-native-nfc-manager and Web NFC do, on each platform's own API: iOS's Core NFC with the system's sheet, Android's reader mode, and Web NFC in Chrome on Android. A Mac, a PC and Linux answer that they have none.

s := nfc.Start(nfc.Options{Alert: "Hold your iPhone near the tag."}, func(t *nfc.Tag) {
	if u, ok := t.Message.URI(); ok {
		link.Set(u)
	}
	s.Stop()
})

examples/nfc reads the link on a tag and writes one to it.

Is NFC there and on

nfc.Check says whether the device has NFC (Supported) and whether it's on (Enabled); not on the main thread. nfc.Use is the same as a signal for a component, which follows Android's switch while the component lives; nfc.Watch calls a function with each change.

state := nfc.Use()
ui.Show(signal.Func(func() bool { s := state.Get(); return s.Supported && !s.Enabled }), func() ui.Node {
	return ui.Button(ui.ButtonProps{Title: ui.Val("Turn NFC On"), OnPress: func() { go nfc.OpenSettings() }})
})

iPhones have NFC from the iPhone 7, and no switch for it: Enabled is Supported there. iPads and the simulator have none. On Android, OpenSettings opens the system's NFC settings for the user to turn it on; elsewhere it's ErrNotAvailable. A browser can't tell whether NFC is off until a session finds it off (ErrDisabled).

Reading tags: sessions

nfc.Start begins a session that looks for tags and calls its function, on the main thread, with each one it finds. Called in a component (its body, an effect), the session ends with the component's owner; from an event handler, it lasts until Stop, Fail, or (iOS) the user closes the sheet or it times out. One session runs at a time: starting one ends the one before.

Options.OnEnd is called as the session ends: nil when the app ended it, nfc.ErrCanceled when the user closed iOS's sheet, nfc.ErrTimeout after iOS's sixty seconds, and ErrNotAvailable, ErrDisabled or ErrDenied when it couldn't begin.

A Tag is what the tag said as it was found: its ID, its Techs, its NDEF status (NDEF: Format, Capacity, CanMakeReadOnly, Android's Type) and its Message (nil if none was read), with the details of its technology where the platform gives them (ISO7816, FeliCa, ISO15693, MIFARE, NfcA, NfcB, Barcode, MaxTransceive).

One tag at a time

A session hands the app one tag, and holds it while the app works with it: reads it again, writes it, sends it commands. Then Next lets it go and looks for another. A tag that comes near while the app holds one waits for Next. On iOS, Next restarts polling, which finds a tag that's still near again; Android finds a tag only as it comes near.

nfc.Start(nfc.Options{OnEnd: ended}, func(t *nfc.Tag) {
	count.Update(func(n int) int { return n + 1 })
	s.Next() // the next tag
})

iOS's sheet

On iOS a session shows the system's sheet. Options.Alert is what it says while it looks; SetAlert changes it ("Writing…"). Stop closes the sheet with its tick and the alert's message; Fail("Couldn't write the tag.") closes it with that failure. Android and the web show no sheet: the app shows its own, and the alert does nothing there.

Options.Poll chooses the session. Without it, iOS's NFCNDEFReaderSession reads tags with an NDEF message: its tags have no ID and take no raw commands. With it (nfc.PollA, PollB, PollF, PollV, PollPACE, or PollAll), iOS's NFCTagReaderSession polls for those kinds of tags, with their IDs and commands. ISO 7816 cards need their applications in asuka.json's nfc.iso7816, and FeliCa cards their system codes in nfc.felica: iOS finds no others.

Android's reader mode

On Android a session is reader mode (enableReaderMode) for the screen in front, so tags come to the app and not to other apps, and Android doesn't show its own tag screen. It's taken again for an Activity that comes back to the front. Options.Poll is reader mode's flags (none: every kind); SkipNDEF doesn't read the NDEF message as a tag is found (FLAG_READER_SKIP_NDEF_CHECK: faster for tags that only take commands); NoSound turns off the platform's sound, for the app's own (ui.Haptic); PresenceDelay is how often Android checks the tag is still there.

NDEF messages and records

An NDEF message is a nfc.Message: its Records, each a TNF, a Type, an ID and a Payload. These make the records apps use most:

Message.URI is the first record's URI (a URI record, an absolute URI, a smart poster's), the one Android opens the app with; Message.Text the first text. Message.Encode and nfc.Decode are the message's bytes, as a tag holds them (Decode joins chunked records); an empty tag's message is one empty record, which decodes to an empty Message.

Writing and making tags read-only

While the app holds a tag, Write replaces its message, and MakeReadOnly locks it for good: no one can write it again. Both wait for the tag: call them from a goroutine, then go back to the main thread for the session.

nfc.Start(nfc.Options{Alert: "Hold your iPhone near a tag to write it."}, func(t *nfc.Tag) {
	if !t.NDEF.Writable() {
		s.Fail("This tag can't be written.")
		return
	}
	s.SetAlert("Writing…")
	go func() {
		err := t.Write(nfc.Message{nfc.URI("https://example.com/t/42")})
		ui.Post(func() {
			if err != nil {
				s.Fail("Couldn't write the tag.")
				return
			}
			s.Stop()
		})
	}()
})

Write fails with ErrReadOnly on a locked tag and ErrTooLarge for a message larger than NDEF.Capacity; a Formatable tag (not NDEF yet, Android's NdefFormatable) is formatted with the message. Read reads the message again, Status the NDEF status. A tag that leaves, or is let go, fails with ErrTagLost.

The tag itself: IDs, technologies, commands

Tag.Techs are the technologies the tag has. Both platforms report nfc.NDEF, ISO7816 (ISO 7816 cards: ISO 14443-4), MIFARE (ISO 14443-3A tags: NTAG, MIFARE Ultralight, DESFire), FeliCa and ISO15693; Android also reports its own (NfcA, NfcB, NfcF, NfcV, IsoDep, MifareClassic, MifareUltralight, NDEFFormatable, NfcBarcode). ID is the tag's identifier as the platform gives it (Android's NFC-V IDs least significant byte first).

Transceive sends a raw command and answers with the response. iOS needs a session with Poll; the web has none (ErrNotSupported).

r, err := t.Command(nfc.SelectAID(aid)) // SELECT by AID
if err == nil && r.OK() {
	r, err = t.Command(nfc.APDU{CLA: 0x00, INS: 0xB0, P1: 0, P2: 0, Le: 256}) // READ BINARY
}

nfc.APDU encodes a command, short or extended as its data and Le need; Response is its Data, SW1 and SW2 (OK: 90 00).

MIFARE Classic's sectors are read and written on Android only (iOS reads no MIFARE Classic): ClassicAuth with a sector's key A or B, then ClassicRead and ClassicWrite of its 16-byte blocks, and ClassicValue for value blocks (Increment, Decrement, Restore, Transfer).

Tags that open the app

A tag can open the app when it isn't open, or bring it to the front:

• iOS reads tags in the background (iPhone XS and later) and offers to open an app for a tag whose first record is one of its universal links: asuka.json's links, whose domains serve the apple-app-site-association file. The link comes to ui.OnOpenURL, as any link does.
• Android opens the app for the tags of asuka.json's nfc.ndef (NDEF_DISCOVERED, by the message's first record: a URI, a MIME type, an external type) and nfc.tech (TECH_DISCOVERED, by technologies). A URI's tag comes to ui.OnOpenURL; the others to nfc.OnOpen, as a Tag the app can still read, write and send commands while it's near. An https tag of one of the app's links opens it as an App Link too.

ui.OnOpenURL(func(u string) { link.Set(u) })
nfc.OnOpen(func(t *nfc.Tag) {
	if mt, ok := t.Message[0].MediaType(); ok && mt == "application/vnd.example.ticket" {
		ticket.Set(string(t.Message[0].Payload))
	}
})

A tag that comes before a handler is set (the one the app launched with) waits for the first. nfc.OnOpen stops with the component's owner, and with the function it returns. A tag that comes while a session runs goes to the session, not here.

asuka.json and permissions

An app that imports asuka/sdk/nfc gets Android's NFC permission and uses-feature android.hardware.nfc (not required: phones without NFC can still install it), and on iOS NFCReaderUsageDescription (write your own in ios.usage) and Core NFC's entitlement, com.apple.developer.nfc.readersession.formats (NDEF and TAG). A release's App ID needs the NFC Tag Reading capability: asuka build says so if its profile lacks it.

asuka.json's nfc adds what the app's tags need:

"nfc": {
  "iso7816": ["D2760000850101"],
  "felica": ["8008"],
  "ndef": [{ "uri": "https://example.com/t/" }, { "mime": "application/vnd.example.ticket" }, { "external": "example.com:ticket" }],
  "tech": [["IsoDep"], ["NfcA", "MifareUltralight"]],
  "required": true
}

They're added only for an app that imports the package. See asuka.json.

In asuka dev

The simulator and the emulator have no NFC: Check says unsupported. On an Android phone, the player has the NFC permission, so sessions, reading, writing and commands all work under asuka dev; tags that open the app don't (the filters are the app's own build's: try them with --no-hot; asuka dev says so). On an iPhone the player's profile needs the NFC Tag Reading capability, and ISO 7816 cards and FeliCa need the app's own build (their AIDs and system codes are its Info.plist's), so asuka dev builds an app with nfc.iso7816 or nfc.felica instead of running it in the player. Web NFC needs a secure context, which --lan's addresses aren't: run asuka dev --platform web, forward its port to the phone (adb reverse tcp:<port> tcp:<port>), and open http://localhost:<port> in Chrome on the phone.

On each platform

A desktop's USB NFC readers are smart card readers (PC/SC): they read cards' APDUs, not tags' NDEF messages in a way that works across readers (each vendor's commands differ), and have no tag to tap from a session's sheet. Asuka leaves them out; a native package can reach them (winscard.dll, pcsc-lite, CryptoTokenKit).

Testing with simulated tags

host/fake's NFC simulates the phone's NFC for an app's UI tests (Testing): Tap brings a tag near the session running, Cancel and Timeout end it as iOS does, Remove takes the tag away, Open opens the app with one, and SetEnabled turns NFC off. A fake.NFCTag holds its NDEF message's bytes, which the app's writes change.

func TestRead(t *testing.T) {
	var n *fake.NFC
	a := uitest.Mount(t, Tags, uitest.Setup(func(h *fake.Host) { n = h.NFC() }))
	a.Tap("Read a Tag")
	a.Until("a session", func() bool { return n.Session != nil })
	n.Tap(&fake.NFCTag{NDEF: nfc.Message{nfc.URI("https://example.com/hello")}.Encode()})
	a.WaitFor("https://example.com/hello")
}

n.Session is the session running, with its Alert, its Poll and the rest of its options; a tag's Transceive and Classic answer its commands.