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:

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 unexpectedly nil

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

@type model() :: binary()
@type vin() :: binary()
@type wait_option() :: {:count, integer()} | {:delay, integer()}
@type wait_options() :: [wait_option()]

Functions

Link to this function

capabilities(session, vin)

View Source
@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

Return values

On success, returns {:ok, capabs}, where capabs is a PorscheConnEx.Struct.Capabilities structure.

On error, returns {:error, _}.

Link to this function

complete(session, pending_request)

View Source
@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

Return values

On success, returns {:ok, result}, where the nature of result depends on the type of request being completed.

On error, returns {:error, _}.

Link to this function

current_overview(session, vin)

View Source
@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

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, _}.

Link to this function

delete_charging_profile(session, vin, model, profile_id)

View Source

Deletes a charging profile for an electric vehicle.

Arguments

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, _}.

Link to this function

delete_timer(session, vin, model, timer_id)

View Source

Deletes a timer for an electric vehicle.

Arguments

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, _}.

Link to this function

emobility(session, vin, model)

View Source
@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

Return values

On success, returns {:ok, emob}, where emob is a PorscheConnEx.Struct.Emobility structure.

On error, returns {:error, _}.

Link to this function

maintenance(session, vin)

View Source
@spec maintenance(PorscheConnEx.Session.t(), vin()) ::
  {:ok, PorscheConnEx.Struct.Maintenance.t()} | {:error, any()}

Returns a list of maintenance events regarding a particular vehicle.

Arguments

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

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

Return values

On success, returns {:ok, position}, where position is a PorscheConnEx.Struct.Position structure.

On error, returns {:error, _}.

Link to this function

put_charging_profile(session, vin, model, profile)

View Source

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

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, _}.

Link to this function

put_timer(session, vin, model, timer)

View Source

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

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, _}.

Link to this function

set_climate(session, vin, on_off)

View Source
@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

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

Return values

On success, returns {:ok, status}, where status is a PorscheConnEx.Struct.Status structure.

On error, returns {:error, _}.

Link to this function

stored_overview(session, vin)

View Source
@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

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

Return values

On success, returns {:ok, summary}, where summary is a PorscheConnEx.Struct.Summary structure.

On error, returns {:error, _}.

Link to this function

trips_long_term(session, vin)

View Source
@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

Return values

On success, returns {:ok, list}, where list is a list of PorscheConnEx.Struct.Trip structures.

On error, returns {:error, _}.

Link to this function

trips_short_term(session, vin)

View Source
@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

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

Return values

On success, returns {:ok, list}, where list is a list of PorscheConnEx.Struct.Vehicle structures.

On error, returns {:error, _}.

Link to this function

wait(session, pending, opts \\ [])

View Source
@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

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, _}.