protocol

Documentation

Overview

Package protocol defines constants and errors used by the Tesla API.

Subdirectories contain autogenerated protobuf code.

Index

• Constants
• Variables
• func GetError(u *universal.RoutableMessage) error
• func IsNominalError(err error) bool
• func LoadPublicKey(filename string) (*ecdh.PublicKey, error)
• func MayHaveSucceeded(err error) bool
• func NewError(message string, mayHaveSucceeded bool, temporary bool) error
• func PublicKeyBytesFromHex(h string) (*ecdh.PublicKey, error)
• func SavePrivateKey(skey ECDHPrivateKey, filename string) error
• func ShouldRetry(err error) bool
• func Temporary(err error) bool
• type CommandError
  • func (e *CommandError) Error() string
  • func (e *CommandError) MayHaveSucceeded() bool
  • func (e *CommandError) Temporary() bool
  • func (e *CommandError) Unwrap() error
• type Domain
• type ECDHPrivateKey
  • func LoadPrivateKey(filename string) (ECDHPrivateKey, error)
  • func UnmarshalECDHPrivateKey(keyBytes []byte) ECDHPrivateKey
• type Error
• type KeychainError
  • func (e *KeychainError) Error() string
  • func (e *KeychainError) MayHaveSucceeded() bool
  • func (e *KeychainError) Temporary() bool
• type NominalError
  • func (e *NominalError) Error() string
  • func (e *NominalError) MayHaveSucceeded() bool
  • func (e *NominalError) Temporary() bool
  • func (e *NominalError) Unwrap() error
• type NominalVCSECError
  • func (n *NominalVCSECError) Error() string
  • func (n *NominalVCSECError) MayHaveSucceeded() bool
  • func (n *NominalVCSECError) Temporary() bool
• type Receiver
• type RoutableMessageError
  • func (v *RoutableMessageError) Error() string
  • func (v *RoutableMessageError) MayHaveSucceeded() bool
  • func (v *RoutableMessageError) Temporary() bool

Constants

const (
	// DomainVCSEC handles (un)lock, remote start drive, keychain management commands.
	DomainVCSEC = universal.Domain_DOMAIN_VEHICLE_SECURITY
	// DomainInfotainment handles commands that terminate on the vehicle's infotainment system.
	DomainInfotainment = universal.Domain_DOMAIN_INFOTAINMENT
)

Variables

var (
	// ErrBusy indicates a resource is temporarily unavailable.
	ErrBusy = NewError("vehicle busy or finishing wake-up", false, true)
	// ErrUnknown indicates the client received an unrecognized error code. Check for package
	// updates.
	ErrUnknown = NewError("vehicle responded with an unrecognized status code", false, false)
	// ErrNotConnected indicates the vehicle could not be reached.
	ErrNotConnected = NewError("vehicle not connected", false, false)
	// ErrNoSession indicates the client has not established a session with the vehicle. You may
	// have forgotten to call vehicle.StartSessions(...).
	ErrNoSession = NewError("cannot send authenticated command before establishing a vehicle session", false, false)
	// ErrRequiresKey indicates a client tried to send a command without an ECDHPrivateKey.
	ErrRequiresKey = NewError("no private key available", false, false)
	// ErrInvalidPublicKey indicates a client tried to perform an operation with an invalid public
	// key. Public keys are NIST-P256 EC keys, encoded in uncompressed form.
	ErrInvalidPublicKey     = authentication.ErrInvalidPublicKey
	ErrKeyNotPaired         = NewError("vehicle rejected request: your public key has not been paired with the vehicle", false, false)
	ErrUnpexpectedPublicKey = errors.New("remote public key changed unexpectedly")
	ErrBadResponse          = errors.New("invalid response")
	ErrProtocolNotSupported = errors.New("vehicle does not support protocol -- use REST API")
	ErrRequiresBLE          = errors.New("command can only be sent over BLE")
	ErrRequiresEncryption   = errors.New("command should not be sent in plaintext or encrypted with an unauthenticated public key")
)

Functions

func GetError

func GetError(u *universal.RoutableMessage) error

GetError translates a universal.RoutableMessage into an appropriate Error, returning nil if the universal.RoutableMessage did not contain an error.

func IsNominalError

func IsNominalError(err error) bool

func LoadPublicKey

func LoadPublicKey(filename string) (*ecdh.PublicKey, error)

LoadPublicKey loads a P256 EC public key from a file.

The function is flexible, supporting the following formats (note that this list includes private key files, for convenience):

• PKIX PEM ("BEGIN PUBLIC KEY")
• Non-password protected PKCS8 PEM ("BEGIN PRIVATE KEY")
• SEC1 ("BEGIN EC PRIVATE KEY")
• Binary uncompressed SEC1 curve point (0x04, ..., 65 bytes)
• Hex-encoded uncompressed SEC1 curve point (04..., 130 bytes)

func MayHaveSucceeded

func MayHaveSucceeded(err error) bool

MayHaveSucceeded returns true if err is a CommandError that indicates the command may have been executed but the client did not receive a confirmation from the vehicle.

func NewError

func NewError(message string, mayHaveSucceeded bool, temporary bool) error

func PublicKeyBytesFromHex

func PublicKeyBytesFromHex(h string) (*ecdh.PublicKey, error)

PublicKeyBytesFromHex verifies h encodes a valid public key and returns the binary encoding.

func SavePrivateKey

func SavePrivateKey(skey ECDHPrivateKey, filename string) error

func ShouldRetry

func ShouldRetry(err error) bool

ShouldRetry returns true if the client should retry to issue the command that triggered an error.

func Temporary

func Temporary(err error) bool

Temporary returns true if err is a CommandError that indicates the command failed due to possibly transient conditions that do not require user action to resolve.

Types

type CommandError

type CommandError struct {
	Err               error
	PossibleSuccess   bool
	PossibleTemporary bool
}

func (*CommandError) Error

func (e *CommandError) Error() string

func (*CommandError) MayHaveSucceeded

func (e *CommandError) MayHaveSucceeded() bool

func (*CommandError) Temporary

func (e *CommandError) Temporary() bool

func (*CommandError) Unwrap

func (e *CommandError) Unwrap() error

type Domain

type Domain = universal.Domain

Domain identifies the vehicle subsystem to route a command to. Each Domain manages its own key pair.

type ECDHPrivateKey

type ECDHPrivateKey authentication.ECDHPrivateKey

func LoadPrivateKey

func LoadPrivateKey(filename string) (ECDHPrivateKey, error)

LoadPrivateKey loads a P256 EC private key from a file.

func UnmarshalECDHPrivateKey

func UnmarshalECDHPrivateKey(keyBytes []byte) ECDHPrivateKey

type Error

type Error interface {
	error

	// MayHaveSucceeded returns true if the Error was triggered a command that might have been executed.
	// For example, if a client times out while waiting for a response, then the client cannot tell
	// if the command was received. (Not all timeouts mean the command MayHaveSucceeded, so the
	// common Timeout() error interface is not appropriate here).
	MayHaveSucceeded() bool

	// Temporary returns true if the Error might be the result of a transient condition. For
	// example, it's not unusual for the car to return Busy errors if it's in the process of waking
	// from sleep and the services responsible for executing the command are not yet running.
	Temporary() bool
}

Error exposes methods useful for categorizing errors.

type KeychainError

type KeychainError struct {
	Code vcsec.WhitelistOperationInformation_E
}

KeychainError represents an error that occurred while trying to modify a vehicle's keychain.

func (*KeychainError) Error

func (e *KeychainError) Error() string

func (*KeychainError) MayHaveSucceeded

func (e *KeychainError) MayHaveSucceeded() bool

func (*KeychainError) Temporary

func (e *KeychainError) Temporary() bool

type NominalError

type NominalError struct {
	Details error
}

NominalVCSECError indicates the vehicle received and authenticated a command, but could not execute it.

func (*NominalError) Error

func (e *NominalError) Error() string

func (*NominalError) MayHaveSucceeded

func (e *NominalError) MayHaveSucceeded() bool

func (*NominalError) Temporary

func (e *NominalError) Temporary() bool

func (*NominalError) Unwrap

func (e *NominalError) Unwrap() error

type NominalVCSECError

type NominalVCSECError struct {
	Details *verror.NominalError
}

NominalVCSECError indicates the vehicle security controller received and authenticated a command, but could not execute it.

func (*NominalVCSECError) Error

func (n *NominalVCSECError) Error() string

func (*NominalVCSECError) MayHaveSucceeded

func (n *NominalVCSECError) MayHaveSucceeded() bool

func (*NominalVCSECError) Temporary

func (n *NominalVCSECError) Temporary() bool

type Receiver

type Receiver interface {
	Recv() <-chan *universal.RoutableMessage
	Close()
}

A Receiver provides a channel for receiving universal.RoutableMessages from a remote peer.

Typically a Receiver is returned by a function that sends a request to a vehicle, and the channel only carries a single response to that request.

type RoutableMessageError

type RoutableMessageError struct {
	Code universal.MessageFault_E
}

RoutableMessageError represents a protocol-layer error.

func (*RoutableMessageError) Error

func (v *RoutableMessageError) Error() string

func (*RoutableMessageError) MayHaveSucceeded

func (v *RoutableMessageError) MayHaveSucceeded() bool

func (*RoutableMessageError) Temporary

func (v *RoutableMessageError) Temporary() bool