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.Sessionprocess (by PID or by name) - a
PorscheConnEx.Session.RequestDatastructure
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
requiredbut 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.pendingis aPorscheConnEx.Client.PendingRequeststructure.
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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be updated.modelis the model identifier of the vehicle to be updated.profile_idis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be updated.modelis the model identifier of the vehicle to be updated.timer_idis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be queried.modelis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.pendingis aPorscheConnEx.Client.PendingRequeststructure.
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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be updated.modelis the model identifier of the vehicle to be updated.profileis aPorscheConnEx.Struct.Emobility.ChargingProfilestructure.
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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be updated.modelis the model identifier of the vehicle to be updated.timeris aPorscheConnEx.Struct.Emobility.Timerstructure.
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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis the VIN of the vehicle to be updated.on_offis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.vinis 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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.
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
sessionis aPorscheConnEx.Sessionpid/name or aPorscheConnEx.Session.RequestDatastructure.pendingis aPorscheConnEx.Client.PendingRequeststructure.optsis 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, _}.