[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