README

我卖掉了我的大众汽车，当然也不再是车联网客户，所以我不能再维护这个仓库。它将保留在这里供参考。如果您在自己的项目中遇到任何问题，认为我可以帮助解答，请参阅文档底部的“联系”。

适用于 VW Car-Net API 的非官方 PHP 封装

此软件包试图遵循 此文档 中概述的建议和指南，详细说明了 VW Car-Net API 的操作。此软件包及其代码将立即反映对该文档所做的任何更改。

安装

建议您使用 Composer 安装此软件包。

composer require thomasesmith/php-vw-car-net

地区支持

到目前为止，此软件包仅与 美国 VW Car-Net 账户 正式测试过。不清楚它将如何与美国的 Car-Net 账户外的工作，也不清楚它将如何与 VW WeConnect 账户一起工作。如果您想帮助测试，请这样做。

快速开始

现在您只需要一个良好的 VW Car-Net 账户...

use thomasesmith\VWCarNet;

$Auth = new VWCarNet\Authentication();  
$Auth->authenticate("YOUR CAR NET EMAIL ADDRESS", "YOUR CAR NET PASSWORD");
$CN = new VWCarNet\API($Auth, "YOUR CAR NET PIN");

var_dump($CN->getVehicleStatus());

...将会返回...

array(10) {
  ["currentMileage"]=>
  int(55788)
  ["timestamp"]=>
  int(1597167320003)
  ["exteriorStatus"]=>
  array(5) {
    ["secure"]=>
    string(6) "SECURE"
    ["doorStatus"]=>
    array(8) {
      ["frontLeft"]=>
      string(6) "CLOSED"
      ["frontRight"]=>
      string(6) "CLOSED"
      ["rearLeft"]=>
      string(6) "CLOSED"
      ["rearRight"]=>
      string(6) "CLOSED"
      ["trunk"]=>
      string(6) "CLOSED"
      ["hood"]=>
      string(6) "CLOSED"
    }
    ["doorLockStatus"]=>
    array(4) {
      ["frontLeft"]=>
      string(6) "LOCKED"
      ["frontRight"]=>
      string(6) "LOCKED"
      ["rearLeft"]=>
      string(6) "LOCKED"
      ["rearRight"]=>
      string(6) "LOCKED"
    }
    ["windowStatus"]=>
    array(7) {
      ["frontLeft"]=>
      string(6) "CLOSED"
      ["frontRight"]=>
      string(6) "CLOSED"
      ["rearLeft"]=>
      string(6) "CLOSED"
      ["rearRight"]=>
      string(6) "CLOSED"
    }
    ["lightStatus"]=>
    array(5) {
      ["left"]=>
      string(3) "OFF"
      ["right"]=>
      string(3) "OFF"
    }
  }
  ["powerStatus"]=>
  array(5) {
    ["cruiseRange"]=>
    int(131)
    ["fuelPercentRemaining"]=>
    int(0)
    ["cruiseRangeUnits"]=>
    string(2) "KM"
    ["cruiseRangeFirst"]=>
    int(131)
    ["battery"]=>
    array(4) {
      ["chargePercentRemaining"]=>
      int(100)
      ["minutesUntilFullCharge"]=>
      int(15)
      ["chargePlug"]=>
      string(9) "PLUGGEDIN"
      ["triggeredByTimer"]=>
      string(5) "false"
    }
  }
  ["location"]=>
  array(2) {
    ["latitude"]=>
    float(35.123456)
    ["longitude"]=>
    float(-120.123456)
  }
  ["lastParkedLocation"]=>
  array(2) {
    ["latitude"]=>
    float(35.123456)
    ["longitude"]=>
    float(-120.123456)
  } 
  ["lockStatus"]=>
  string(6) "LOCKED"
}

在 API 对象中可用的所有方法

getVehiclesAndEnrollmentStatus(): array

这将返回一个关于您的 Car-Net 账户的信息关联数组，但最重要的是将包含一个 vehicleEnrollmentStatus 数组，其中每个与您的账户关联的车辆都将有自己的详细数组，包括它们的 vehicleId 值。

getAllVehicles(): array

这只是一个到上述响应中 vehicleEnrollmentStatus 数组的快捷方式。如果不需要或不需要该响应的其他部分。

setCurrentlySelectedVehicle(string $vehicleId): array

此方法接受一个 vehicleId 作为其唯一参数，并将其设置为您的“当前车辆”，即您将通过后续方法调用执行的车辆。它将使用此车辆，直到当然将其设置为其他值。

如果您只关联了一辆车辆到您的Car-Net账户，您根本不需要设置此选项，因为您当前选择的车辆将默认为getVehiclesAndEnrollmentStatus()车辆列表中列出的第一辆。

getVehicleStatus([布尔值 $refetch]): 数组

此方法返回一个关联数组，包含当前所选车辆的所有详细信息及其各种状态，例如车门锁定状态、电池状态、窗户状态、巡航范围、行驶里程等。

实际上，此方法只会在您第一次调用它时获取车辆状态。之后，它将返回第一次获取的保存结果。如果您想重新获取状态，您必须传递此方法的一个参数，一个可选的布尔值。传递值为true将强制重新获取状态。它将等待获取完成，然后以不带参数的方式返回响应。

"重新获取"状态不应与"重新轮询"状态混淆。这两个功能是不同的。强制重新获取比重新轮询要“便宜”一些，有时这正是您需要的。

requestRepollOfVehicleStatus(): void

有时车辆返回的信息可能会有些过时，调用此方法强制Car-Net API重新轮询车辆以获取您当前所选车辆的最新状态。受请求速率限制约束

调用此方法将自动强制下一个调用getVehicleStatus()时重新获取状态。

此方法调用后，状态大约需要25秒才能实际更新。因此，在调用getVehicleStatus()之前，请等待大约这么长时间，以便给车辆时间来执行您的命令。

getVehicleId(): 字符串

此方法返回包含当前所选车辆ID值的字符串。

getBatteryStatus(): 数组

仅限电动车 这只是一个快捷方式，返回getVehicleStatus()输出中包含的powerStatus数组。

getClimateStatus(): 数组

此方法返回一个关联数组，包含当前所选车辆气候系统的所有详细信息：室外温度、气候控制系统是否正在运行、除霜器是否正在运行，以及这些条件是否由离车计时器触发。受请求速率限制约束

setUnpluggedClimateControl(bool $enabled): void

仅限电动车 传递布尔值false将禁用您当前所选车辆在未插电时开启气候系统。布尔值true将允许车辆在未插电时使用气候系统。此方法不返回任何内容。受请求速率限制约束

此设置在车辆中持续存在，您无需每次执行代码时都设置它。

setClimateControl(bool $enabled [, int $temperatureDegrees]): void

将布尔值false作为第一个参数传入将关闭当前选定车辆中的气候系统。布尔值true将开启它。额外的仅限电动汽车功能：使用可选的第二个参数设置您希望车辆尝试达到的目标温度。如果没有传入整型值，则使用汽车的默认值。此方法不返回任何内容。受请求速率限制

如果当前选定的车辆是电动汽车，它必须已插电，或者您必须确保setUnpluggedClimateControl()设置为true。

setDefroster(bool $enabled): void

传入布尔值true将启动您当前选定的车辆的除霜器。布尔值false将停止它。此方法不返回任何内容。受请求速率限制

如果当前选定的车辆是电动汽车，您的汽车必须已插电，或者您必须确保setUnpluggedClimateControl()设置为true。

setCharge(bool $enabled): void

仅限电动汽车传入布尔值true将启动您当前选定车辆的电池充电器。布尔值false将停止它。此方法不返回任何内容。受请求速率限制

setLock(bool $enabled): void

传入布尔值true将锁定您当前选定车辆的车门。布尔值false将解锁它们。此方法不返回任何内容。受请求速率限制

getVehicleHealthReport([boolean $refetch]): array

此方法返回一个关联数组，包含您当前选定车辆的健康报告。受请求速率限制

实际上，此方法仅在您第一次调用它时获取车辆的健康报告。之后，它将返回第一次获取的保存结果。如果您想实际重新获取状态，您必须传入此方法的单个参数，一个可选的布尔值。传入值为true将强制它重新获取健康报告。它将等待该获取完成，然后像没有参数一样返回响应。

“重新获取”健康报告不应与“重新轮询”健康报告混淆。这两个功能是不同的。

requestRepollOfVehicleHealthReport(): void

与车辆状态一样，健康报告可能会稍微过时，因此调用此方法强制Car-Net API重新轮询汽车，获取当前选定车辆的更新健康报告。此方法不返回任何内容。受请求速率限制

调用此方法将自动强制下一次调用getVehicleHealthReport()重新获取状态。

在调用此方法后，健康报告大约需要25秒才能实际更新。因此，在等待一段时间后再调用getVehicleHealthReport()，而不要立即调用。

“请求速率限制”是什么意思？

许多API对象方法都执行Car-Net API强加的严格速率限制请求。这些方法在本文档中使用短语“受请求速率限制”表示。如果您的账户在一段时间内发出过多请求，这些方法将开始抛出类似于“429 Too Many Requests”的消息的异常。

在您的请求开始被429状态码拒绝之前，允许的请求数量和时间是多少是未知的。您必须等待多长时间才能再次期望您的请求得到满足也是未知的。

目前请小心使用这些。

存储您的令牌非常重要！

认证对象将完成所有获取和持有所需访问令牌的工作，并在它们过期时自动刷新它们，但它只会持有这些令牌，直到您的脚本执行结束。除非您在那些执行之间将它们持久化存储在某处，否则不这样做将迫使您的应用程序每次运行时都需要重新认证，这会使您的应用程序非常慢。

认证类有三个方法可以帮助您完成这项任务：setSaveCallback()、getAllAuthenticationTokens()和setAuthenticationTokens()

平面文件方法

保存您的访问令牌的一种既便宜又简单的方法是将认证实例序列化并保存到平面文件中。如果您的应用程序足够简单，并且您认为这可以适用于您，那么它可能看起来像这样

use thomasesmith\VWCarNet;

// ...

$authObjectFilename = __DIR__ . '/AuthenticationObjectStore';

$tokenChangeCallback = function($Auth) use ($authObjectFilename) {
    file_put_contents($authObjectFilename, serialize($Auth));
};


if (file_exists($authObjectFilename)) {

    $Auth = unserialize(file_get_contents($authObjectFilename)); 

    // Be sure to just make sure this instance's save callback function is set.
    $Auth->setSaveCallback($tokenChangeCallback);    

} else {
    
    // No flat file found, so create one.
    try {
        $Auth = new VWCarNet\Authentication();  

        $Auth->setSaveCallback($tokenChangeCallback);
        /* 
        The order here is important! This instance's setSaveCallback() method
        must be called before authenticate() is, to make sure it has something
        to perform at the very end of the authenticate() method. 
        */

        // Finally, perform the actual authentication process.
        $Auth->authenticate("YOUR CAR NET EMAIL ADDRESS", "YOUR CAR NET PASSWORD");

    } catch (Exception $e) {
        // Any issue that arises while logging in will throw an exception here.
        print $e->getMessage(); 
    }
}


// Now create an instance of the API object and pass in the Auth instance 
// as the first parameter, and your Car-Net PIN as the second, and you're set
$CN = new VWCarNet\API($Auth, "YOUR CAR NET PIN");

// ...

或者，以您希望的方式保存它们

如果您想以其他方式持久化存储令牌，那么它可能看起来更像以下伪代码

use thomasesmith\VWCarNet;

// ...

$tokenChangeCallback = function($Auth) {

    $tokensArray = $Auth->getAllAuthenticationTokens();

    // ...
    // Here you'd put code to persistently store the $tokensArray
    // in whatever manner you with
    // ... 
};

// ...
// Code to load the tokens array from your persistent store
$loadedTokensArray = [];
// ... 

if ($loadedTokensArray) {

    // If you have 'em, use 'em.
    $Auth = new VWCarNet\Authentication();  
    $Auth->setAuthenticationTokens($loadedTokensArray);
    $Auth->setSaveCallback($tokenChangeCallback); 

} else {

    // If you don't, get new ones and be sure to use setSaveCallback() so store them.
    try {

        $Auth = new VWCarNet\Authentication();  
        $Auth->setSaveCallback($tokenChangeCallback); // Must be called BEFORE authenticate() is
        $Auth->authenticate("YOUR CAR NET EMAIL ADDRESS", "YOUR CAR NET PASSWORD");

    } catch (Exception $e) {
        // Any issue that arises while logging in will throw an exception here.
        print $e->getMessage(); 
    }
}


// Now create an instance of the API object and pass in the Auth instance 
// as the first parameter, and your Car-Net PIN as the second, and you're set
$CN = new VWCarNet\API($Auth, "YOUR CAR NET PIN");

// ...

辅助方法

在API对象中包含了一些静态辅助方法，这些方法在使用此包时可能很有用。

API::kilometersToMiles(int $kilometers): int

Car-Net API似乎默认使用千米作为距离单位，因此如果您更喜欢英制单位，您必须将它们进行转换。该方法接受表示千米的int，并返回表示其约等英里数的int。

$kilometersCruiseRange = $CN->getVehicleStatus()['powerStatus']['cruiseRange']; // 122
echo VWCarNet\API::kilometersToMiles($kilometersCruiseRange) . " miles"; // echoes: 76 miles

API::fahrenheitToCelsius(int $celsius): int

Car-Net API似乎默认使用华氏度作为温度单位，因此如果您更喜欢公制单位，您必须将它们进行转换。该方法接受表示华氏度的int，并返回表示其约等摄氏度的int。

$outdoorTempF = $CN->getClimateStatus()['outdoor_temperature']; // 78 
echo  VWCarNet\API::fahrenheitToCelsius($outdoorTempF) . " celsius"; // echoes: 26 celsius;

API::codeCaseToWords(string $weirdCaseString): string

API在命名其属性键时不一致，一些使用驼峰式命名（例如，“frontLeft”，“sunRoof”），而另一些使用蛇形命名（例如，“outdoor_temperature”）。如果您想在您的应用程序中使用这些名称，但希望将它们转换为普通英语，则此方法接受驼峰式或蛇形字符串，并尽可能返回包含普通英语单词的字符串，单词之间由空格字符分隔。

foreach ($CN->getVehicleStatus()['exteriorStatus']['doorLockStatus'] as $position => $status) {
  // Here, $position can equal "frontLeft", "frontRight", "rearLeft", etc.
  echo VWCarNet\API::codeCaseToWords($position) . " door is " . strtolower($status) . "." . PHP_EOL;
}

/*

The above will print:

Front left door is unlocked.
Front right door is locked.
Rear left door is locked.
Rear right door is locked.

*/

免责声明

不应暗示此包的开发者与大众汽车股份公司之间有任何关联或赞助。任何商标、服务标志、品牌名称或标志均为其各自所有者的财产，并仅在本网站上用于教育目的。