[Ovmsdev] Fwd: HTTP API
Mark Webb-Johnson
mark at webb-johnson.net
Fri Mar 1 15:13:47 HKT 2013
Tom,
That is cellular utilisation. Migrated from the old ovms_utilisation table into the new historicaldata, so everything is stored the same.
Record types for *-OVM-Utilisation:
0: car_rx
1: car_tx
2: app_rx
3: app_tx
It is the daily bytes transmitted to/from the car and apps. Used to drive the Cellular Usage chart in the Apps. Doesn't include cellular or network overhead - just the data the server saw.
This historical data system is amazingly flexible. I'm working on adding an option for drive and charge logs to it. Michael B's already got Twizzy battery and gps logs - and the GPS log stuff will get moved over to work on any vehicle.
Regards, Mark.
P.S. The *-OVM-DebugCrash is also really cool. It was also contributed by Michael B and allows us to see what happened each time a car module firmware was started (including the cause of the start and the where in the code it was).
On 1 Mar, 2013, at 2:27 PM, Tom Saxton wrote:
> 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
>
>
> _______________________________________________
> OvmsDev mailing list
> OvmsDev at lists.teslaclub.hk
> http://lists.teslaclub.hk/mailman/listinfo/ovmsdev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openvehicles.com/pipermail/ovmsdev/attachments/20130301/2b64d161/attachment.htm>
More information about the OvmsDev
mailing list