github.com/taglme/nfc-goclient

Taglme Desktop Golang SDK

Official open-source Golang SDK library for Taglme Desktop. Quick and efficient way to connect applications with NFC REST API server.

Reference Documentation

This SDK is intended to use in conjunction with Taglme Desktop REST API server. It is a thin API wrapper. The main goal of the SDK is to handle requests complexity by hiding unnecessary details.

• REST API specification - this is full REST API specification in Swagger (OpenAPI) format.
• SDK API Reference - docs hosted by pkg.go.dev

Overview of SDK's Packages

SDK consist of several packages

• client - core package with services. Services are used for communication with server API.
• models - basic types and structs
• ndefconv - ndef format conversion operations

Overview of API resources

• Adapter - represents a NFC reader.
• Tag - represents NFC tag.
• Job - represents a set of operations (steps) that should be performed with tag (read, write, format etc). Jobs are added to adapter queue and start execution as soon as tag discovered by adapter.
• JobRun - represents the result of job execution.
• Event - represents the event generated by the server. Events are sent by server through web socket connection. Client should listen for event messages in order to be notified when job execution if finished.

Opening Issues

If you encounter a bug with the SDK for Go we would like to hear about it. Search the existing issues and see if others are also experiencing the issue before opening a new issue. Please include the version of SDK for Go, Go language, and OS you’re using. Please also include reproduction case when appropriate.

The GitHub issues are intended for bug reports and feature requests. For help and questions with using SDK for GO please make use of the resources listed in the Reference Documentation section. Keeping the list of open issues lean will help us respond in a timely manner.

Installation

go get github.com/taglme/nfc-goclient

Dependencies

The SDK includes a vendor folder containing the runtime dependencies of the SDK. The metadata of the SDK's dependencies can be found in the Go module file go.mod

Go Modules

If you are using Go modules, your go get will default to the latest tagged release version of the SDK. To get a specific release version of the SDK use @<tag> in your go get command.

go get github.com/taglme/nfc-goclient@v1.1

To get the latest SDK repository change use @latest.

go get github.com/taglme/nfc-goclient@latest

Usage

Extended examples in /cmd folder

import "github.com/taglme/nfc-goclient/pkg"

//Create new API client
host := "127.0.0.1:3011" // IP address and port of API server
locale := "en" // preferred locale for messages from API server
client := client.New(url, locale)

// Request list of adapters
adapters, err := client.Adapters.GetAll()
// Get ID of the first adapter in list
adapterID:=adapters[0].AdapterID 

//Compose job with transmit bytes operation
opTransmit := models.JobStep{
		Command: models.CommandTransmitTag,
		Params: models.TransmitTagParams{
			TxBytes: []byte{0x60},
		},
	}
newJob := models.NewJob{
		JobName:     "Transmit tag",
		Repeat:      1,
		ExpireAfter: 60,
		Steps: []models.JobStepResource{
			opTransmit.ToResource(),
		},
	}

//Compose job with write NDEF url message operation
ndefMessage := []ndefconv.NdefRecord{
		ndefconv.NdefRecord{
			Type: ndefconv.NdefRecordPayloadTypeUrl,
			Data: ndefconv.NdefRecordPayloadUrl{
				Url: "https://tagl.me",
			},
		},
	}
opWrite := models.JobStep{
		Command: models.CommandWriteNdef,
		Params: models.WriteNdefParams{
			Message: ndefMessage,
		},
	}
newJob := models.NewJob{
		JobName:     "Write NDEF message",
		Repeat:      1,
		ExpireAfter: 60,
		Steps: []models.JobStepResource{
			opWrite.ToResource(),
		},
	}

// Add job to adapter queue
job, err:= client.Jobs.Add(adapterID, newJob)

// Initialize the  WS connection
err := client.Ws.Connect()
defer client.Ws.Disonnect()

eHandler := func(e models.Event) {
    // handle the received event
switch e.Name {
    case models.EventNameJobFinished:
		fmt.Println("[Job finished event]")
    case models.EventNameTagDiscovery:
		fmt.Println("[Tag discovered event]")    
        
    }
}

//Subscribe for server events
client.Ws.OnEvent(eHandler)

Commands and Tools

Make could be used to execute some tasks

• build – build package
• lint – run linter
• test – run tests
• deps – manage dependencies

CLI tool - fully functional CLI for API server based on this SDK.

License

This SDK is distributed under the MIT license