vehicle command
v0.2.1
تدعم سيارات Tesla الآن بروتوكولًا يوفر مصادقة الأوامر الشاملة. تستخدم حزمة Golang البروتوكول الجديد للتحكم في وظائف السيارة، مثل التحكم في المناخ والشحن.
من بين الأدوات المضمنة خادم وكيل HTTP الذي يحول مكالمات REST API إلى بروتوكول قيادة السيارة الجديد.
قد يكون بعض المطورين على دراية بواجهة برمجة تطبيقات مالك Tesla. ستتوقف واجهة برمجة تطبيقات المالك عن العمل عندما تبدأ المركبات في طلب مصادقة الأوامر الشاملة. إذا كنت أحد هؤلاء المطورين، فيمكنك إعداد الخادم الوكيل أو إعادة بناء تطبيقك لاستخدام هذه المكتبة مباشرةً. لا تدعم مركبات الطراز S وX قبل عام 2021 هذا البروتوكول الجديد. سوف تستمر واجهة برمجة تطبيقات الأسطول في العمل على هذه المركبات.
تتم مصادقة الأمر في خطوتين:
لذا، لإرسال أمر إلى مركبة، يجب أن يحصل تطبيق جهة خارجية على رمز OAuth صالح من المستخدم، ويجب على المستخدم تسجيل المفتاح العام للتطبيق في السيارة.
يحتوي موقع Tesla على الويب على تعليمات للحصول على رموز OAuth المميزة. يحتوي ملف README هذا على تعليمات لإنشاء مفاتيح خاصة وتوجيه المستخدم إلى تدفق تسجيل المفتاح العام. يمكن للأدوات الموجودة في هذا المستودع استخدام رمز OAuth والمفتاح الخاص لإرسال الأوامر إلى المركبات.
على سبيل المثال، يتضمن المستودع واجهة سطر الأوامر:
tesla-control -ble -key-file private_key.pem lockوخادم وكيل REST API (الذي يتم توفيره بمفتاح خاص عند التشغيل ويستخدم رموز OAuth المميزة التي يرسلها العملاء):
curl --cacert cert.pem
--header 'Content-Type: application/json'
--header "Authorization: Bearer $TESLA_AUTH_TOKEN"
--data '{}'
"https://localhost:4443/api/1/vehicles/$VIN/command/door_lock"
متطلبات:
خطوات التثبيت:
go get ./...go build ./...go install ./...يقوم الأمر الأخير بتثبيت الأدوات المساعدة التالية:
تتوفر صورة Docker لتشغيل هذه الأدوات. تقوم الصورة افتراضيًا بتشغيل وكيل HTTP، لكن علامة --entrypoint تغير الأداة التي سيتم استخدامها.
قم بتشغيل الصورة من Docker hub:
docker pull tesla/vehicle-command:latest
docker run tesla/vehicle-command:latest --help
# running a different tool
docker run --entrypoint tesla-control tesla/vehicle-command:latest --helpيتم أيضًا توفير مثال لملف docker-compose.yml.
docker compose upيمكن استخدام متغيرات البيئة التالية بدلاً من إشارات سطر الأوامر.
TESLA_KEY_NAME لاشتقاق اسم الإدخال للمفتاح الخاص لمصادقة الأمر الخاص بك في حلقة مفاتيح النظام لديك.TESLA_TOKEN_NAME لاشتقاق اسم الإدخال لرمز OAuth المميز في حلقة مفاتيح النظام لديك.TESLA_KEYRING_TYPE لتجاوز نوع حلقة مفاتيح النظام الافتراضية لنظام التشغيل لديك. قم بتشغيل tesla-keygen -h لرؤية القيم المدعومة المدرجة في وثائق علامة -keyring-type . راجع وثائق حلقة المفاتيح للحصول على تفاصيل حول كل خيار.TESLA_VIN رقم تعريف المركبة. يمكنك العثور على رقم VIN الخاص بك ضمن عناصر التحكم > البرنامج في واجهة المستخدم الخاصة بسيارتك. (على الرغم من الاسم، تحتوي أرقام VIN على أحرف وأرقام).TESLA_CACHE_FILE ملفًا يقوم بتخزين معلومات الجلسة مؤقتًا. تسمح ذاكرة التخزين المؤقت للبرامج بتخطي إرسال رسائل المصافحة إلى السيارة. يؤدي ذلك إلى تقليل زمن الوصول وعدد مكالمات Fleet API التي يجريها العميل عند إعادة الاتصال بمركبة بعد إعادة التشغيل. وهذا مفيد بشكل خاص عند استخدام tesla-control ، الذي يُعاد تشغيله عند كل استدعاء.TESLA_HTTP_PROXY_TLS_CERT ملف شهادة TLS لوكيل HTTP.TESLA_HTTP_PROXY_TLS_KEY ملف مفتاح TLS لوكيل HTTP.TESLA_HTTP_PROXY_HOST المضيف لوكيل HTTP.TESLA_HTTP_PROXY_PORT المنفذ لوكيل HTTP.TESLA_HTTP_PROXY_TIMEOUT المهلة التي سيستخدمها وكيل HTTP عند الاتصال بخوادم Tesla.TESLA_VERBOSE التسجيل المطول. مدعوم من tesla-control و tesla-http-proxy .على سبيل المثال:
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonعند هذه النقطة، أنت جاهز لاستخدام أداة سطر الأوامر لبدء إرسال الأوامر إلى سيارتك الشخصية عبر BLE! وبدلاً من ذلك، تابع القراءة أدناه لتتعلم كيفية إنشاء تطبيق يمكنه إرسال الأوامر عبر الإنترنت باستخدام REST API.
يصف هذا القسم كيفية إعداد وكيل HTTP واستخدامه، والذي يسمح للعملاء بإرسال أوامر المركبة باستخدام REST API.
كما تمت مناقشته أعلاه، سيحتاج وكيل HTTP الخاص بك إلى المصادقة مع Tesla (باستخدام رموز OAuth المميزة) ومع المركبات الفردية (باستخدام مفتاح خاص).
تتطلب خوادم Tesla من عميلك توفير رمز وصول OAuth قبل أن يقوم بإعادة توجيه الأوامر إلى السيارة. يجب عليك الحصول على رمز OAuth المميز من مالك السيارة. راجع موقع Tesla الإلكتروني للحصول على إرشادات حول تسجيل حساب مطور والحصول على رموز OAuth المميزة.
حتى إذا كان لدى عميلك رمز مميز صالح، فإن السيارة تقبل فقط الأوامر المصرح بها بواسطة المفتاح الخاص لعميلك.
تقوم الأداة المساعدة tesla-keygen المضمنة في هذا المستودع بإنشاء مفتاح خاص، وتخزينه في حلقة مفاتيح النظام لديك، وطباعة المفتاح العام المقابل:
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
تستخدم حلقة مفاتيح النظام مساحة تخزين بيانات الاعتماد المعتمدة على نظام التشغيل لديك باعتبارها حلقة مفاتيح النظام. في نظام التشغيل macOS، على سبيل المثال، يتم افتراضيًا استخدام سلسلة مفاتيح تسجيل الدخول الخاصة بك. قم بتشغيل tesla-keygen -h لمزيد من الخيارات.
ستؤدي إعادة تشغيل أمر tesla-keygen إلى طباعة نفس المفتاح العام دون الكتابة فوق المفتاح الخاص. يمكنك إجبار الأداة على الكتابة فوق مفتاح عام موجود باستخدام -f .
تتحقق المركبات من الأوامر باستخدام المفاتيح العامة. يجب تسجيل مفتاحك العام على مركبات المستخدمين قبل أن يقبلوا الأوامر المرسلة بواسطة تطبيقك.
إليك عملية التسجيل من وجهة نظر المالك:
لكي تنجح هذه العملية، يجب عليك تسجيل اسم النطاق الذي يحدد تطبيقك. سيعرض تطبيق Tesla اسم النطاق هذا للمستخدم عندما يسأله عما إذا كان يرغب في الموافقة على طلبك، وستعرض السيارة اسم النطاق بجوار المفتاح في شاشة الأقفال.
اتبع التعليمات لتسجيل مفتاحك العام والمجال الخاص بك. المفتاح العام المشار إليه في تلك التعليمات هو ملف public_key.pem في المثال أعلاه.
بمجرد تسجيل مفتاحك العام بنجاح، قم بتزويد مالكي المركبات برابط إلى https://tesla.com/_ak/<your_domain_name> . على سبيل المثال، إذا قمت بتسجيل example.com ، فقم بتوفير رابط إلى https://tesla.com/_ak/example.com . سيتولى تطبيق Tesla iPhone أو Android الرسمي للهاتف المحمول (الإصدار 4.27.3 أو أعلى) الباقي. يجب على العملاء الذين لديهم أكثر من منتج واحد من منتجات Tesla تحديد السيارة المطلوبة قبل النقر على الرابط أو مسح رمز الاستجابة السريعة ضوئيًا.
يتطلب وكيل HTTP شهادة خادم TLS. لأغراض الاختبار والتطوير، يمكنك إنشاء شهادة خادم مضيف محلي موقعة ذاتيًا باستخدام OpenSSL:
mkdir config
openssl req -x509 -nodes -newkey ec
-pkeyopt ec_paramgen_curve:secp521r1
-pkeyopt ec_param_enc:named_curve
-subj '/CN=localhost'
-keyout config/tls-key.pem -out config/tls-cert.pem -sha256 -days 3650
-addext "extendedKeyUsage = serverAuth"
-addext "keyUsage = digitalSignature, keyCertSign, keyAgreement"
يقوم هذا الأمر بإنشاء مفتاح خاص غير مشفر، config/tls-key.pem .
يمكن تشغيل الخادم الوكيل باستخدام الأمر التالي:
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443ويمكن أيضًا تشغيله باستخدام Docker:
# option 1: using docker run
docker pull tesla/vehicle-command:latest
docker run -v ./config:/config -p 127.0.0.1:4443:4443 tesla/vehicle-command:latest -tls-key /config/tls-key.pem -cert /config/tls-cert.pem -key-file /config/fleet-key.pem -host 0.0.0.0 -port 4443
# option 2: using docker compose
docker compose up ملاحظة: في مرحلة الإنتاج، من المحتمل أن ترغب في حذف -port 4443 والاستماع إلى المنفذ القياسي 443.
يوضح هذا القسم كيف يمكن للعملاء الوصول إلى الخادم باستخدام curl . يتحمل العملاء مسؤولية الحصول على رموز OAuth المميزة. احصل على رمز OAuth المميز كما هو موضح أعلاه.
نقاط النهاية التي لا تدعم المصادقة الشاملة يتم تفويضها إلى واجهة برمجة تطبيقات REST الخاصة بشركة Tesla:
export TESLA_AUTH_TOKEN= < access-token >
export VIN= < vin >
curl --cacert cert.pem
--header " Authorization: Bearer $TESLA_AUTH_TOKEN "
" https://localhost:4443/api/1/vehicles/ $VIN /vehicle_data "
| jq -r . يتم اعتراض نقاط النهاية التي تدعم المصادقة الشاملة وإعادة كتابتها بواسطة الوكيل، الذي يعالج حالة الجلسة ويعيد المحاولة. بعد نسخ cert.pem إلى العميل الخاص بك، سيؤدي تشغيل الأمر التالي من العميل إلى قيام الوكيل بإرسال أمر flash_lights إلى السيارة:
export TESLA_AUTH_TOKEN= < access-token >
export VIN= < vin >
curl --cacert cert.pem
--header ' Content-Type: application/json '
--header " Authorization: Bearer $TESLA_AUTH_TOKEN "
--data ' {} '
" https://localhost:4443/api/1/vehicles/ $VIN /command/flash_lights " التدفق للحصول على $TESLA_AUTH_TOKEN :
تدفق الأمر عبر النظام:
يقوم وكيل HTTP بتنفيذ نقاط نهاية أوامر مركبة Tesla Fleet API.
قد يستخدم العملاء القديمون المكتوبون لـ Owner API معرف API الخاص بمالك السيارة عند إنشاء مسارات URL. يتطلب الخادم الوكيل من العملاء استخدام رقم VIN مباشرة بدلاً من ذلك.
يمكنك قراءة وثائق الحزمة على pkg.go.dev.
يدعم هذا المستودع go mod ويتبع دلالات إصدار Go. لاحظ أن إصدارات v0.xx لا تضمن استقرار واجهة برمجة التطبيقات (API).
