rfms

README

rFMS Go

A Go SDK and CLI tool for rFMS APIs.

SDK

Features

• Full support for the rFMS 4.0.0 standard
• Backwards-compatibility with the rFMS 2.1.1 standard (JSON)
• Support for vendor-specific fields from Scania

Supported OEMs

• Scania
• Volvo Trucks

Installing

$ go get github.com/way-platform/rfms-go@latest

Using

client := rfms.NewClient(
    rfms.WithScania(os.Getenv("SCANIA_CLIENT_ID"), os.Getenv("SCANIA_CLIENT_SECRET")),
)
lastVIN, moreDataAvailable := "", true
for moreDataAvailable {
    response, err := client.Vehicles(context.Background(), &rfms.VehiclesRequest{
        LastVIN: lastVIN,
    })
    if err != nil {
        panic(err)
    }
    for _, vehicle := range response.Vehicles {
        fmt.Println(vehicle.VIN)
    }
    moreDataAvailable = response.MoreDataAvailable
    if moreDataAvailable {
        lastVIN = response.Vehicles[len(response.Vehicles)-1].VIN
    }
}

Developing

Build project

The project is built using Mage, see magefile.go.

$ ./tools/mage build

For all available build tasks, see:

$ ./tools/mage -l

CLI tool

The rfms CLI tool enables interaction with rFMS APIs from the command line.

Installing

go install github.com/way-platform/rfms-go/cmd/rfms@latest

Using

$ rfms auth login scania --client-id $CLIENT_ID --client-secret $CLIENT_SECRET

Logged in to SCANIA.

$ rfms vehicles
{
  "authorizedPaths": [
    "/vehiclepositions",
    "/vehiclestatuses"
  ],
  "brand": "SCANIA",
  "customerVehicleName": "testingapp3",
  "type": "TRUCK",
  "vin": "YS2RKSTO01TT00068"
}
{
  "authorizedPaths": [
    "/vehiclepositions",
    "/vehiclestatuses"
  ],
  "brand": "SCANIA",
  "customerVehicleName": "Pins. Truck",
  "type": "TRUCK",
  "vin": "YS2R4X2000TT00396"
}

License

This SDK is published under the MIT License.

Security

Security researchers, see the Security Policy.

Code of Conduct

Be nice. For more info, see the Code of Conduct.

Documentation

Overview

Package rfms provides primitives for interacting with rFMS v4 APIs.

Index

• Constants
• type Client
  • func NewClient(opts ...ClientOption) *Client
  • func (c *Client) VehiclePositions(ctx context.Context, request VehiclePositionsRequest) (_ VehiclePositionsResponse, err error)
  • func (c *Client) VehicleStatuses(ctx context.Context, request VehicleStatusesRequest) (_ VehicleStatusesResponse, err error)
  • func (c *Client) Vehicles(ctx context.Context, request VehiclesRequest) (_ VehiclesResponse, err error)
• type ClientConfig
• type ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithBasicAuth(username string, password string) ClientOption
  • func WithLogger(logger Logger) ClientOption
  • func WithRetryCount(retryCount int) ClientOption
  • func WithReuseTokenAuth(credentials TokenCredentials) ClientOption
  • func WithScania(clientID string, clientSecret string) ClientOption
  • func WithScaniaAuth(clientID string, clientSecret string) ClientOption
  • func WithTransport(transport http.RoundTripper) ClientOption
  • func WithVersion(apiVersion Version) ClientOption
  • func WithVolvoTrucks(username string, password string) ClientOption
• type Error
  • func (e *Error) Error() string
• type Logger
• type TokenAuthenticator
  • func NewScaniaTokenAuthenticator(clientID string, clientSecret string) TokenAuthenticator
• type TokenCredentials
• type VehiclePositionsRequest
• type VehiclePositionsResponse
• type VehicleStatusesRequest
• type VehicleStatusesResponse
• type VehiclesRequest
• type VehiclesResponse
• type Version

Examples

• Client (Scania)
• Client (VolvoTrucks)

Constants

const (
	BrandDAF         = "DAF"
	BrandDaimler     = "DAIMLER"
	BrandIrisbus     = "IRISBUS"
	BrandIveco       = "IVECO"
	BrandIvecoBuses  = "IVECO BUS"
	BrandMAN         = "MAN"
	BrandRenault     = "RENAULT TRUCKS"
	BrandScania      = "SCANIA"
	BrandVDL         = "VDL"
	BrandVolvoBuses  = "VOLVO BUSES"
	BrandVolvoTrucks = "VOLVO TRUCKS"
)

Known rFMS brands, based on rFMS v4.

const (
	// 0x00 Not available (NONE).
	FuelTypeNotAvailable = "00"
	// 0x01 Gasoline/petrol (GAS).
	FuelTypeGasoline = "01"
	// 0x02 Methanol (METH).
	FuelTypeMethanol = "02"
	// 0x03 Ethanol (ETH).
	FuelTypeEthanol = "03"
	// 0x04 Diesel (DSL).
	FuelTypeDiesel = "04"
	// 0x05 Liquefied Petroleum Gas (LPG).
	FuelTypeLiquefiedPetroleumGas = "05"
	// 0x06 Compressed Natural Gas (CNG).
	FuelTypeCompressedNaturalGas = "06"
	// 0x07 Propane (PROP).
	FuelTypePropane = "07"
	// 0x08 Battery/electric (ELEC).
	FuelTypeBatteryElectric = "08"
	// 0x1D Fuel Cell Utilizing Hydrogen.
	FuelTypeHydrogenFuelCell = "1D"
	// 0x1E Hydrogen Internal Combustion Engine.
	FuelTypeHydrogenInternalCombustionEngine = "1E"
	// 0x1F Kerosene.
	FuelTypeKerosene = "1F"
	// 0x20 Heavy Fuel Oil.
	FuelTypeHeavyFuelOil = "20"
)

Known fuel type values (based on J1939 SPN5837).

const (
	ScaniaBaseURL      = "https://dataaccess.scania.com/rfms4"
	ScaniaAuthBaseURL  = "https://dataaccess.scania.com/auth"
	VolvoTrucksBaseURL = "https://api.volvotrucks.com/rfms"
)

Known rFMS base URLs.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an rFMS API client.

Example (Scania)

client := rfms.NewClient(
	rfms.WithScania(os.Getenv("SCANIA_CLIENT_ID"), os.Getenv("SCANIA_CLIENT_SECRET")),
)
lastVIN, moreDataAvailable := "", true
for moreDataAvailable {
	response, err := client.Vehicles(context.Background(), rfms.VehiclesRequest{
		LastVIN: lastVIN,
	})
	if err != nil {
		panic(err)
	}
	for _, vehicle := range response.Vehicles {
		fmt.Println(vehicle.GetVin())
	}
	moreDataAvailable = response.MoreDataAvailable
	if moreDataAvailable {
		lastVIN = response.Vehicles[len(response.Vehicles)-1].GetVin()
	}
}

Example (VolvoTrucks)

client := rfms.NewClient(
	rfms.WithVolvoTrucks(os.Getenv("VOLVO_TRUCKS_USERNAME"), os.Getenv("VOLVO_TRUCKS_PASSWORD")),
)
lastVIN, moreDataAvailable := "", true
for moreDataAvailable {
	response, err := client.Vehicles(context.Background(), rfms.VehiclesRequest{
		LastVIN: lastVIN,
	})
	if err != nil {
		panic(err)
	}
	for _, vehicle := range response.Vehicles {
		fmt.Println(vehicle.GetVin())
	}
	moreDataAvailable = response.MoreDataAvailable
	if moreDataAvailable {
		lastVIN = response.Vehicles[len(response.Vehicles)-1].GetVin()
	}
}

func NewClient

func NewClient(opts ...ClientOption) *Client

NewClient creates a new Client with the given base URL and options.

func (*Client) VehiclePositions

func (c *Client) VehiclePositions(ctx context.Context, request VehiclePositionsRequest) (_ VehiclePositionsResponse, err error)

VehiclePositions implements the rFMS API method "GET /vehiclepositions".

func (*Client) VehicleStatuses

func (c *Client) VehicleStatuses(ctx context.Context, request VehicleStatusesRequest) (_ VehicleStatusesResponse, err error)

func (*Client) Vehicles

func (c *Client) Vehicles(ctx context.Context, request VehiclesRequest) (_ VehiclesResponse, err error)

Vehicles implements the rFMS API method "GET /vehicles".

type ClientConfig

type ClientConfig struct {
	// contains filtered or unexported fields
}

ClientConfig is the configuration for a Client.

type ClientOption

type ClientOption func(*ClientConfig)

ClientOption is an option that configures a Client.

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets the API base URL for the Client.

func WithBasicAuth

func WithBasicAuth(username string, password string) ClientOption

WithBasicAuth authenticates requests using HTTP basic authentication.

func WithLogger

func WithLogger(logger Logger) ClientOption

WithLogger sets the Logger for the Client.

func WithRetryCount

func WithRetryCount(retryCount int) ClientOption

WithRetryCount sets the maximum number of times to retry a request.

func WithReuseTokenAuth

func WithReuseTokenAuth(credentials TokenCredentials) ClientOption

WithReuseTokenAuth authenticates requests by re-using existing TokenCredentials.

func WithScania

func WithScania(clientID string, clientSecret string) ClientOption

WithScania configures the Client to use the Scania rFMS v4 API.

func WithScaniaAuth

func WithScaniaAuth(clientID string, clientSecret string) ClientOption

WithScaniaAuth authenticates requests using Scania's HMAC-SHA256 challenge-response mechanism.

func WithTransport

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport sets the http.RoundTripper HTTP transport for the Client.

func WithVersion

func WithVersion(apiVersion Version) ClientOption

WithVersion sets the rFMS API version for the Client.

func WithVolvoTrucks

func WithVolvoTrucks(username string, password string) ClientOption

WithVolvoTrucks configures the Client to use the Volvo Trucks rFMS v2.1 API.

type Error

type Error struct {
	// Method is the HTTP method used to make the request.
	Method string
	// URL is the URL of the request.
	URL string
	// Status is the HTTP status.
	Status string
	// StatusCode is the HTTP status code.
	StatusCode int
	// RateLimitReset is the duration until the rate limit is reset.
	RateLimitReset time.Duration
	// Identifier of the rFMS error.
	Identifier string
	// Description of the rFMS error.
	Description string
	// ErrorURI provides more information about the error.
	ErrorURI string
}

Error is an error returned by the rFMS API.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

type Logger

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Warn(msg string, keysAndValues ...any)
	Error(msg string, keysAndValues ...any)
}

Logger is a leveled logger interface.

type TokenAuthenticator

type TokenAuthenticator interface {
	// Authenticate the client and return a set of [TokenCredentials].
	Authenticate(ctx context.Context) (TokenCredentials, error)
	// Refresh the token credentials.
	Refresh(ctx context.Context, refreshToken string) (TokenCredentials, error)
}

TokenAuthenticator is a pluggable interface for authenticating requests to an rFMS API.

func NewScaniaTokenAuthenticator

func NewScaniaTokenAuthenticator(clientID string, clientSecret string) TokenAuthenticator

NewScaniaTokenAuthenticator creates a new TokenAuthenticator for Scania's rFMS API.

type TokenCredentials

type TokenCredentials struct {
	// Token is the bearer token for the authenticated client.
	Token string `json:"token"`
	// TokenExpireTime is the time when the token expires.
	TokenExpireTime time.Time `json:"tokenExpireTime"`
	// RefreshToken is the refresh token for the authenticated client.
	RefreshToken string `json:"refreshToken"`
	// RefreshTokenExpireTime is the time when the refresh token expires.
	RefreshTokenExpireTime time.Time `json:"refreshTokenExpireTime"`
}

TokenCredentials for an authenticated rFMS API client.

type VehiclePositionsRequest

type VehiclePositionsRequest struct {
	// LastVIN is the last VIN included in the previous response.
	LastVIN string
	// DateType indicates whether the start/stop times are compared to created or received time.
	DateType string
	// StartTime to filter positions (only positions after this time).
	StartTime time.Time
	// StopTime to filter positions (only positions before this time).
	StopTime time.Time
	// VIN to filter positions for a specific vehicle.
	VIN string
	// LatestOnly returns only the latest position for each vehicle.
	LatestOnly bool
	// TriggerFilter filters positions by trigger type.
	TriggerFilter string
}

VehiclePositionsRequest is the request for the Client.VehiclePositions method.

type VehiclePositionsResponse

type VehiclePositionsResponse struct {
	// VehiclePositions in the response.
	VehiclePositions []*rfmsv5.VehiclePosition `json:"vehiclePositions"`
	// MoreDataAvailable indicates if there is more data available.
	MoreDataAvailable bool `json:"moreDataAvailable"`
	// RequestServerDateTime is the server time when the request was received.
	RequestServerDateTime time.Time `json:"requestServerDateTime,omitzero"`
}

VehiclePositionsResponse is the response for the Client.VehiclePositions method.

type VehicleStatusesRequest

type VehicleStatusesRequest struct {
	// LastVIN is the last VIN included in the previous response.
	LastVIN string
	// DateType indicates whether the start/stop times are compared to created or received time.
	DateType string
	// StartTime to filter statuses (only statuses after this time).
	StartTime time.Time
	// StopTime to filter statuses (only statuses before this time).
	StopTime time.Time
	// VIN to filter statuses for a specific vehicle.
	VIN string
	// ContentFilter filters statuses by content type (ACCUMULATED, SNAPSHOT, UPTIME).
	ContentFilter []string
	// TriggerFilter filters statuses by trigger type.
	TriggerFilter []string
	// LatestOnly returns only the latest status for each vehicle.
	LatestOnly bool
}

VehicleStatusesRequest is the request for the Client.VehicleStatuses method.

type VehicleStatusesResponse

type VehicleStatusesResponse struct {
	// VehicleStatuses in the response.
	VehicleStatuses []*rfmsv5.VehicleStatus `json:"vehicleStatuses"`
	// MoreDataAvailable indicates if there is more data available.
	MoreDataAvailable bool `json:"moreDataAvailable"`
	// RequestServerDateTime is the server time when the request was received.
	RequestServerDateTime time.Time `json:"requestServerDateTime,omitzero"`
}

VehicleStatusesResponse is the response for the Client.VehicleStatuses method.

type VehiclesRequest

type VehiclesRequest struct {
	// LastVIN is the last VIN included in the previous response.
	LastVIN string `json:"lastVin"`
}

VehiclesRequest is the request for the Client.Vehicles method.

type VehiclesResponse

type VehiclesResponse struct {
	// Vehicles in the response.
	Vehicles []*rfmsv5.Vehicle `json:"vehicles"`
	// MoreDataAvailable indicates if there is more data available.
	MoreDataAvailable bool `json:"moreDataAvailable"`
}

VehiclesResponse is the response for the Client.Vehicles method.

type Version

type Version string

Version is the version of the rFMS API.

const (
	V4   Version = "v4"
	V2_1 Version = "v2.1"
)

Currently supported versions of the rFMS API.