[Ovmsdev] Fwd: HTTP API

Tom Saxton tom at idleloop.com
Fri Mar 1 14:27:55 HKT 2013


Very cool!

I see that the /api/historical/<VEHICLEID> returns a list of the types of
records available via the h_recordtype field.

I mostly understand the *-OVM-DebugCrash records, but how do we interpret
the *-OVM-Utilisation records?

    Tom

on 2/28/13 10:02 PM, Mark Webb-Johnson wrote:

> I've implemented some more of this. Current status is that the following have
> been implemented and are now live and working on tmc server:
> 
>> GET     /api/cookie                             Login and return a session
>> cookie
>> DELETE  /api/cookie                             Delete the session cookie and
>> logout
>> GET     /api/vehicles                           Return a list of registered
>> vehicles
>> GET /api/protocol/<VEHICLEID>  Return raw protocol records (no vehicle
>> connection)
>> GET /api/status/<VEHICLEID>   Return vehicle status
>> GET /api/tpms/<VEHICLEID>   Return toms status
>> GET /api/location/<VEHICLEID>  Return vehicle location
>> GET /api/charge/<VEHICLEID>   Return vehicle charge status
>> GET /api/historical/<VEHICLEID>  Request historical data summary
>> GET /api/historical/<VEHICLEID>/<DATATYPE> Request historical data records
> 
> 
> The following are still being worked on:
> 
>> GET /api/vehicle/<VEHICLEID>  Connect to, and return vehicle information
>> DELETE /api/vehicle/<VEHICLEID>  Disconnect from vehicle
>> PUT /api/charge/<VEHICLEID>   Set vehicle charge status
>> DELETE /api/charge/<VEHICLEID>   Abort a vehicle charge
>> GET /api/lock/<VEHICLEID>   Return vehicle lock status
>> PUT /api/lock/<VEHICLEID>   Lock a vehicle
>> DELETE /api/lock/<VEHICLEID>   Unlock a vehicle
>> GET /api/valet/<VEHICLEID>   Return valet status
>> PUT /api/valet/<VEHICLEID>   Enable valet mode
>> DELETE /api/valet/<VEHICLEID>   Disable valet mode
>> GET /api/features/<VEHICLEID>  Return vehicle features
>> PUT /api/feature/<VEHICLEID>  Set a vehicle feature
>> GET /api/parameters/<VEHICLEID>  Return vehicle parameters
>> PUT /api/parameter/<VEHICLEID>  Set a vehicle parameter
>> PUT /api/reset/<VEHICLEID>   Reset the module in a particular vehicle
>> PUT /api/homelink/<VEHICLEID>  Activate home link
> 
> Feel free to have a play.
> 
> Regards, Mark.
> 
> P.S. API is still being changed, so I don't suggest you write production code
> to it yet (until it has been documented and is stable).
> 
> Begin forwarded message:
> 
>> From: Mark Webb-Johnson <mark at webb-johnson.net>
>> Subject: [Ovmsdev] Fwd: HTTP API
>> Date: 22 February, 2013 10:17:23 PM GMT+08:00
>> To: OVMS Developers <ovmsdev at lists.teslaclub.hk>
>> Reply-To: OVMS Developers <ovmsdev at lists.teslaclub.hk>
>> 
>> 
>> I've done some work on this, and tidied up the foundational servers. I've now
>> got a basic framework working in the non-blocking environment of
>> ovms_server.pl.
>> 
>> You can try this yourself using http://tmc.openvehicles.com/api. At the
>> moment I've only enabled HTTP. I'll enable HTTPS (the server already supports
>> it - I just need to install the certificates) when we are ready for
>> production.
>> 
>> The first thing you must do to use the api is authenticate to establish a
>> session and get a cookie (so you don't need to authenticate every time). This
>> is done with a http "GET /api/cookie" passing parameters 'username' and
>> 'password' as your www.openvehicles.com username and password respectively.
>> 
>> $ curl -v -X GET -c cookiejar
>> http://tmc.openvehicles.com:6868/api/cookie?username=USERNAME\&password=PASSW
>> ORD
>> * About to connect() to tmc.openvehicles.com port 6868 (#0)
>> *   Trying 64.111.70.40...
>> * connected
>> * Connected to tmc.openvehicles.com (64.111.70.40) port 6868 (#0)
>>> GET /api/cookie?username=USERNAME&password=PASSWORD HTTP/1.1
>>> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0
>>> OpenSSL/0.9.8r zlib/1.2.5
>>> Host: tmc.openvehicles.com:6868
>>> Accept: */*
>>> 
>> * HTTP 1.0, assume close after body
>> < HTTP/1.0 200 Authentication ok
>> < Connection: close
>> < Content-Length: 9
>> < Cache-Control: max-age=0
>> < Content-Type: text/plain
>> * Added cookie ovmsapisession="9ed66d0e-5768-414e-b06d-476f13be40ff" for
>> domain tmc.openvehicles.com, path /api/, expire 0
>> < Set-Cookie: ovmsapisession=9ed66d0e-5768-414e-b06d-476f13be40ff
>> < Date: Fri, 22 Feb 2013 12:43:56 GMT
>> < Expires: Fri, 22 Feb 2013 12:43:56 GMT
>> < 
>> Login ok
>> 
>> Once logged in, all subsequent requests should pass the cookie
>> (ovmsapisession). The session will expire after 3 minutes of no use, or you
>> can specifically terminate / logout the session by calling "DELETE
>> /api/cookie".
>> 
>> We could have other authentication mechanisms, but I'm really trying to move
>> to a simple username/password mechanism.
>> 
>> To obtain a list of vehicles on your account, you can use the "GET
>> /api/vehicles" call:
>> 
>> $ curl -v -X GET -b cookiejar http://tmc.openvehicles.com:6868/api/vehicles
>> * About to connect() to tmc.openvehicles.com port 6868 (#0)
>> *   Trying 64.111.70.40...
>> * connected
>> * Connected to tmc.openvehicles.com (64.111.70.40) port 6868 (#0)
>>> GET /api/vehicles HTTP/1.1
>>> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0
>>> OpenSSL/0.9.8r zlib/1.2.5
>>> Host: tmc.openvehicles.com:6868
>>> Accept: */*
>>> Cookie: ovmsapisession=9ed66d0e-5768-414e-b06d-476f13be40ff
>>> 
>> * HTTP 1.0, assume close after body
>> < HTTP/1.0 200 Logout ok
>> < Connection: close
>> < Content-Length: 280
>> < Cache-Control: max-age=0
>> < Content-Type: application/json
>> < Date: Fri, 22 Feb 2013 12:44:41 GMT
>> < Expires: Fri, 22 Feb 2013 12:44:41 GMT
>> < 
>> [
>>   {"id":"DEMO","v_apps_connected":0,"v_net_connected":1},
>>   {"id":"MARKSCAR","v_apps_connected":1,"v_net_connected":1},
>>   {"id":"QCCAR","v_apps_connected":0,"v_net_connected":0},
>>   {"id":"RALLYCAR","v_apps_connected":0,"v_net_connected":0},
>>   {"id":"TESTCAR","v_apps_connected":0,"v_net_connected":0}
>> ]
>> 
>> (note that the above is re-formatted slightly, to make it clearer to read).
>> 
>> The return data is a json formatted array of hashes. Each record is one for
>> one vehicle and shows you the vehicle id, as well as counts for the number of
>> apps currently connected to that vehicle, and whether the vehicle is
>> connected to the net (server) or not.
>> 
>> From the server point of view, we can treat an api session just like an app
>> session. From the vehicle point of view there will be no difference - once an
>> API connects to a vehicle, the server will send a "Z 1" message to tell the
>> module it has a connection. If the session times out or is logged out, the
>> server will inform the modules in the vehicles.
>> 
>> The above has all been implemented, and you can try it.
>> 
>> The following commands are what I am thinking about:
>> 
>> GET /api/protocol/<VEHICLEID>  Return raw protocol records (no vehicle
>> connection)
>> 
>> GET /api/vehicle/<VEHICLEID>  Connect to, and return vehicle information
>> DELETE /api/vehicle/<VEHICLEID>  Disconnect from vehicle
>> 
>> GET /api/status/<VEHICLEID>   Return vehicle status
>> 
>> GET /api/tpms/<VEHICLEID>   Return toms status
>> 
>> GET /api/location/<VEHICLEID>  Return vehicle location
>> 
>> GET /api/charge/<VEHICLEID>   Return vehicle charge status
>> PUT /api/charge/<VEHICLEID>   Set vehicle charge status
>> DELETE /api/charge/<VEHICLEID>   Abort a vehicle charge
>> 
>> GET /api/lock/<VEHICLEID>   Return vehicle lock status
>> PUT /api/lock/<VEHICLEID>   Lock a vehicle
>> DELETE /api/lock/<VEHICLEID>   Unlock a vehicle
>> 
>> GET /api/valet/<VEHICLEID>   Return valet status
>> PUT /api/valet/<VEHICLEID>   Enable valet mode
>> DELETE /api/valet/<VEHICLEID>   Disable valet mode
>> 
>> GET /api/features/<VEHICLEID>  Return vehicle features
>> PUT /api/feature/<VEHICLEID>  Set a vehicle feature
>> 
>> GET /api/parameters/<VEHICLEID>  Return vehicle parameters
>> PUT /api/parameter/<VEHICLEID>  Set a vehicle parameter
>> 
>> PUT /api/reset/<VEHICLEID>   Reset the module in a particular vehicle
>> 
>> PUT /api/homelink/<VEHICLEID>  Activate home link
>> 
>> GET /api/historical/<VEHICLEID>  Request historical data summary
>> GET /api/historical/<VEHICLEID>/<DATATYPE> Request historical data records
>> 
>> Thoughts / suggestions?
>> 
>> Regards, Mark.
>> 
>> Begin forwarded message:
>> 
>>> From: Mark Webb-Johnson <mark at webb-johnson.net>
>>> Subject: [Ovmsdev] HTTP API
>>> Date: 18 February, 2013 9:41:15 AM HKT
>>> To: OVMS Developers <ovmsdev at lists.teslaclub.hk>
>>> Reply-To: OVMS Developers <ovmsdev at lists.teslaclub.hk>
>>> 
>>> 
>>> For some time now I've wanted to offer an HTTP API for OVMS. The existing
>>> car<->server and server<->app protocol is cool, but requires going through
>>> some hoops (perl, whatever) to handle the encryption and protocol level
>>> stuff. An HTTP API would make this much easier to externally script, and
>>> would be great for pulling down logs and other such things.
>>> 
>>> I've now completed work re-factoring the ovms_server.pl code to add the
>>> framework to support this:
>>> 
>>> Switched to using the AnyEvent::HTTPD cpan module for the base framework.
>>> Implemented an HTTP server on tcp/6868.
>>> Implemented an HTTPS server on tcp/6869.
>>> Support serving of arbitrary files (in httpfiles directory) for HTTP and
>>> HTTPS.
>>> Implemented syncing of Drupal user accounts (and password hashes) to new
>>> ovms_owners table.
>>> Extended the protocol to support syncing owners and well as vehicle records.
>>> Support syncing ovms_owners table to connected OVMS servers.
>>> Moved ovms_utilisation to ovms_historicalmessages as type
>>> '*-OVM-Utilisation", with records 0 (car_rx), 1 (car_tx), 2 (app_rx) and 3
>>> (app_tx).
>>> 
>>> The above work has just been PUSHed to github.
>>> 
>>> So, the framework exists. Now for the fun stuff.
>>> 
>>> My thinking is:
>>> 
>>> Authenticate to a vehicle either by vehicle + serverpass, or OVMS
>>> username+password.
>>> You can get a list of vehicles by providing your OVMS username+password.
>>> Use cookies to maintain a session - and time sessions out after a few
>>> minutes of inactivity (or on demand logout).
>>> Basic functions to retrieve current vehicle status, and historical data.
>>> Function to 'connect' to a live vehicle - just like an App, it will keep the
>>> connection open for as long as the session lasts, then tell the vehicle you
>>> have disconnected.
>>> Control functions - just like the apps - start/stop charge, homelink, etc.
>>> Support for OVMS protocol, so can convert the data messages to actual
>>> real-world JSON.
>>> 
>>> Does anyone want to work with me on this? In particular, anyone with RESTful
>>> or other HTTP API experience?
>>> 
>>> Regards, Mark.
>>> 
>>> _______________________________________________
>>> OvmsDev mailing list
>>> OvmsDev at lists.teslaclub.hk
>>> http://lists.teslaclub.hk/mailman/listinfo/ovmsdev
>> 
>> _______________________________________________
>> OvmsDev mailing list
>> OvmsDev at lists.teslaclub.hk
>> http://lists.teslaclub.hk/mailman/listinfo/ovmsdev
> 
> _______________________________________________
> OvmsDev mailing list
> OvmsDev at lists.teslaclub.hk
> http://lists.teslaclub.hk/mailman/listinfo/ovmsdev




More information about the OvmsDev mailing list