View Source PorscheConnEx.Client (porsche_conn_ex v0.1.0)
Issues requests to the Porsche Connect API.
Common arguments
All functions in this module require one of the following as their first argument:
- a
PorscheConnEx.Session
process (by PID or by name) - a
PorscheConnEx.Session.RequestData
structure
This will both configure and authenticate the API call, based
on the starting arguments for the PorscheConnEx.Session
process.
Most calls require the 17-character
VIN of the
vehicle to be queried or altered. This can be retrieved using
PorscheConnEx.Client.vehicles/1
.
Several calls related to electric vehicles also require the vehicle model.
This can be retrieved using PorscheConnEx.Client.capabilities/2
.
Blocking & timeouts
The actual HTTP request will be performed in the calling process and will
block until complete. While there is no explicit per-call timeout, the
effective timeout can be influenced by setting http_options
— see
PorscheConnEx.Config
for details.
Error values
The Porsche Connect API tends to be fairly opaque with server-side errors,
generating the same "unknown error" result for most errors. As a result, the
most common error value from this module will be {:error, :unknown}
.
Hopefully, the cause of the error will be reasonably obvious based on
context.
Lower-level errors will tend to be more descriptive. These may include, but are not limited to, the following:
{:error, :nxdomain}
- cannot find the API DNS name (are you offline?){:error, :not_found}
- any "404 Not Found" HTTP error- usually caused by choosing an unknown locale in your configuration
{:error, :timeout}
- the HTTP request timed out
Higher-level errors occur when the API call is successful, but this library
receives data that it cannot parse. These are represented by {:error, map}
, where map
is a nested map structure indicating which fields failed
to parse and why. Typically this falls into one of two categories:
- An enum (atom) field received a value we haven't seen before
- A value is marked as
required
but is unexpectedlynil
In these cases, I highly encourage users of this library to add the missing
enum or remove the required
and submit a pull request. (We use these
strict data rules specifically so that we know the full range of values the
API might return.)
Summary
Functions
Returns information about the capabilities of a particular vehicle.
Retrieves the final result of a pending request.
Fetches current overview information about a particular vehicle.
Deletes a charging profile for an electric vehicle.
Deletes a timer for an electric vehicle.
Returns comprehensive data about the electric charging status and behaviour of a particular vehicle.
Returns a list of maintenance events regarding a particular vehicle.
Checks the status of a pending request.
Returns the current global position of a particular vehicle.
Creates or updates a charging profile for an electric vehicle.
Creates or updates a timer for an electric vehicle.
Starts or cancels the "direct climatisation" (preheat/cool) feature.
Returns general status information about a particular vehicle.
Returns recent overview information about a particular vehicle.
Returns extremely basic information about a particular vehicle.
Returns a list of long-term trips taken by a particular vehicle.
Returns a list of short-term trips taken by a particular vehicle.
Returns a list of vehicles assigned to the current account.
Polls a pending request until it finishes, then completes it if applicable.
Types
Functions
@spec capabilities(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Capabilities.t()} | {:error, any()}
Returns information about the capabilities of a particular vehicle.
This includes the model identifier, which is used in several other calls relating to electric vehicle batteries and charging.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, capabs}
, where capabs
is a
PorscheConnEx.Struct.Capabilities
structure.
On error, returns {:error, _}
.
@spec complete(PorscheConnEx.Session.t(), PorscheConnEx.Client.PendingRequest.t()) :: {:ok, any()} | {:error, any()}
Retrieves the final result of a pending request.
See PorscheConnEx.Client.PendingRequest
for usage details. Note that this
function only applies to requests that read data, and will not match
write-only requests.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.pending
is aPorscheConnEx.Client.PendingRequest
structure.
Return values
On success, returns {:ok, result}
, where the nature of result
depends on
the type of request being completed.
On error, returns {:error, _}
.
@spec current_overview(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Overview.t()} | {:error, any()}
Fetches current overview information about a particular vehicle.
The vehicle will be queried directly, and the information received should be fully up-to-date. This may take a while, or fail, especially if the vehicle is turned off or has limited cellular signal.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure.
To wait for and retrieve the results, use PorscheConnEx.Client.wait/3
.
Alternatively, you may call PorscheConnEx.Client.poll/2
and
PorscheConnEx.Client.complete/2
directly.
On error, returns {:error, _}
.
@spec delete_charging_profile( PorscheConnEx.Session.t(), vin(), model(), PorscheConnEx.Struct.Emobility.ChargingProfile.id() ) :: {:ok, PorscheConnEx.Client.PendingRequest.t()} | {:error, any()}
Deletes a charging profile for an electric vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be updated.model
is the model identifier of the vehicle to be updated.profile_id
is an integer indicating the slot to be deleted.
For details about the profile_id
value, see
PorscheConnEx.Client.put_charging_profile/4
.
Note that you probably shouldn't try to delete the "General" profile (#4), or any other non-user-defined profiles. (I would assume you'd get an error if you tried, but I'm not brave enough to find out.)
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure. See that structure's
documentation for details.
On error, returns {:error, _}
.
@spec delete_timer( PorscheConnEx.Session.t(), vin(), model(), PorscheConnEx.Struct.Emobility.Timer.id() ) :: {:ok, PorscheConnEx.Client.PendingRequest.t()} | {:error, any()}
Deletes a timer for an electric vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be updated.model
is the model identifier of the vehicle to be updated.timer_id
is an integer indicating the slot to be deleted.
For details about the timer_id
value, see PorscheConnEx.Client.put_timer/4
.
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure. See that structure's
documentation for details.
On error, returns {:error, _}
.
@spec emobility(PorscheConnEx.Session.t(), vin(), model()) :: {:ok, PorscheConnEx.Struct.Emobility.t()} | {:error, any()}
Returns comprehensive data about the electric charging status and behaviour of a particular vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.model
is the model identifier of the vehicle to be queried.
Return values
On success, returns {:ok, emob}
, where emob
is a
PorscheConnEx.Struct.Emobility
structure.
On error, returns {:error, _}
.
@spec maintenance(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Maintenance.t()} | {:error, any()}
Returns a list of maintenance events regarding a particular vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, list}
, where list
is a list of
PorscheConnEx.Struct.Maintenance
structures.
On error, returns {:error, _}
.
@spec poll(PorscheConnEx.Session.t(), PorscheConnEx.Client.PendingRequest.t()) :: {:ok, :success | :in_progress} | {:error, any()}
Checks the status of a pending request.
See PorscheConnEx.Client.PendingRequest
for usage details.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.pending
is aPorscheConnEx.Client.PendingRequest
structure.
Return values
- Returns
{:ok, :in_progress}
if the request is still ongoing. - Returns
{:ok, :success}
if the request completed successfully. - Returns
{:error, :failed}
if the request failed. - Returns
{:error, _}
on other errors.
@spec position(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Position.t()} | {:error, any()}
Returns the current global position of a particular vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, position}
, where position
is a
PorscheConnEx.Struct.Position
structure.
On error, returns {:error, _}
.
@spec put_charging_profile( PorscheConnEx.Session.t(), vin(), model(), PorscheConnEx.Struct.Emobility.ChargingProfile.t() ) :: {:ok, PorscheConnEx.Client.PendingRequest.t()} | {:error, any()}
Creates or updates a charging profile for an electric vehicle.
Charging profiles define basic charging parameters, such as charging targets, preferred charging hours, etc. They can also be tied to a specific geographical location, such as a home or office, in which case they will automatically de/activate based on the vehicle's location.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be updated.model
is the model identifier of the vehicle to be updated.profile
is aPorscheConnEx.Struct.Emobility.ChargingProfile
structure.
Profile slots
There are a limited number of slots available for charging profiles,
identified by the profile.id
field. From testing to date, it appears that
profile #4 is the "General" (default) profile, and profiles 5 through 7 are
"local" (user-defined) profiles.
If profile
has a non-nil id
value, then it will overwrite that slot.
If profile
has a nil id
value, then it will be placed in the first empty
"local" slot. If no such slots are available, this function will return an
error.
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure. See that structure's
documentation for details.
On error, returns {:error, _}
.
@spec put_timer( PorscheConnEx.Session.t(), vin(), model(), PorscheConnEx.Struct.Emobility.Timer.t() ) :: {:ok, PorscheConnEx.Client.PendingRequest.t()} | {:error, any()}
Creates or updates a timer for an electric vehicle.
Timers are used to schedule charging, and/or to climatise (preheat/cool) the vehicle, e.g. in preparation for an upcoming trip.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be updated.model
is the model identifier of the vehicle to be updated.timer
is aPorscheConnEx.Struct.Emobility.Timer
structure.
Timer slots
There are five slots available for timers, identified by the timer.id
field.
If timer
has a non-nil id
value, then it will overwrite that slot.
If timer
has a nil id
value, then it will be placed in the first
empty slot. If no slots are available, this function will return an error.
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure. See that structure's
documentation for details.
On error, returns {:error, _}
.
@spec set_climate(PorscheConnEx.Session.t(), vin(), boolean()) :: {:ok, PorscheConnEx.Client.PendingRequest.t()} | {:error, any()}
Starts or cancels the "direct climatisation" (preheat/cool) feature.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be updated.on_off
is a boolean indicating whether to turn on climatisation (true
) or turn it off (false
).
Climatisation timer
When climatisation is off, turning it on will enable it for the next 60 minutes, after which time it will automatically turn off again.
If climatisation is already in the indicated state, no action will occur, and this timer will not be reset.
Return values
On success, returns {:ok, pending}
, where pending
is a
PorscheConnEx.Client.PendingRequest
structure. See that structure's
documentation for details.
On error, returns {:error, _}
.
@spec status(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Status.t()} | {:error, any()}
Returns general status information about a particular vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, status}
, where status
is a
PorscheConnEx.Struct.Status
structure.
On error, returns {:error, _}
.
@spec stored_overview(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Overview.t()} | {:error, any()}
Returns recent overview information about a particular vehicle.
The vehicle is not queried directly; instead, this call retrieves data stored server-side about the vehicle, based on the vehicle's most recent update.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, overview}
, where overview
is a
PorscheConnEx.Struct.Overview
structure.
On error, returns {:error, _}
.
@spec summary(PorscheConnEx.Session.t(), vin()) :: {:ok, PorscheConnEx.Struct.Summary.t()} | {:error, any()}
Returns extremely basic information about a particular vehicle.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, summary}
, where summary
is a
PorscheConnEx.Struct.Summary
structure.
On error, returns {:error, _}
.
@spec trips_long_term(PorscheConnEx.Session.t(), vin()) :: {:ok, [PorscheConnEx.Struct.Trip.t()]} | {:error, any()}
Returns a list of long-term trips taken by a particular vehicle.
These trips are generated when the user clears the short-term trip list. The most recent one should be a summary of all the short-term trips.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, list}
, where list
is a list of
PorscheConnEx.Struct.Trip
structures.
On error, returns {:error, _}
.
@spec trips_short_term(PorscheConnEx.Session.t(), vin()) :: {:ok, [PorscheConnEx.Struct.Trip.t()]} | {:error, any()}
Returns a list of short-term trips taken by a particular vehicle.
These trips are automatically generated, presumably based on when the vehicle is turned on/off, parked, etc.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.vin
is the VIN of the vehicle to be queried.
Return values
On success, returns {:ok, list}
, where list
is a list of
PorscheConnEx.Struct.Trip
structures.
On error, returns {:error, _}
.
@spec vehicles(PorscheConnEx.Session.t()) :: {:ok, [PorscheConnEx.Struct.Vehicle.t()]} | {:error, any()}
Returns a list of vehicles assigned to the current account.
Arguments
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.
Return values
On success, returns {:ok, list}
, where list
is a list of
PorscheConnEx.Struct.Vehicle
structures.
On error, returns {:error, _}
.
@spec wait( PorscheConnEx.Session.t(), PorscheConnEx.Client.PendingRequest.t(), wait_options() ) :: {:ok, any()} | {:error, any()}
Polls a pending request until it finishes, then completes it if applicable.
See PorscheConnEx.Client.PendingRequest
for usage details.
Arguments
session
is aPorscheConnEx.Session
pid/name or aPorscheConnEx.Session.RequestData
structure.pending
is aPorscheConnEx.Client.PendingRequest
structure.opts
is a keyword-list of options and their values:count
(default: 120) is the maximum number of times to poll before giving up.delay
(default: 1000) is the delay (in milliseconds) to wait between poll attempts.
Return values
If the request ultimately finishes successfully, returns {:ok, result}
,
where the nature of result
depends on the type of request being completed.
(For write-only operations, result
will just be :success
, as per the return
value of poll/2
.)
If the request fails, returns {:error, :failed}
as per the return value of poll/2
.
If the result is still pending after count
polls, returns {:error, :in_progress}
. You may call poll/2
or wait/2
again if you still want to
continue waiting.
On other errors, returns {:error, _}
.