[vz-dev] API

Tue Jul 13 17:33:49 CEST 2010

Hello List,

Thank you for allowing me to address this mailing list in English. My native language being Dutch, a Germanic language. This allows me to understand a basic German writing or conversation. Expressing complex technical matters in German is however not that straightforward.

The FOSDEM presentation [1] will give you an introduction to the Flukso project, the top-level architecture and the technology stack it uses. We use Github as a code and HW design repository [2]. The front-end user API is documented in a blog post [3]. We are expanding the API with start, end and resolution parameters. But the basic usage will still be valid and dead simple:

icarus75 at nimbus:~$ curl -k -v -X GET -H "Accept: application/json" -H "X-Version: 1.0" -H "X-Token: d8a8ab8893ea73f768b66b45234b5c3a" "https://api.flukso.net/sensor/c1411c6b4f9910bbbab09f145f8533b9?interval=hour&unit=watt"

will result in the following JSON array of [timestamp, value] pairs:
[[1279027680,206],[1279027740,203],[1279027800,203],[1279027860,197],[1279027920,203],[1279027980,208],[1279028040,186],[1279028100,134],[1279028160,224],[1279028220,272],[1279028280,272],[1279028340,263],[1279028400,260],[1279028460,266],[1279028520,263],[1279028580,265],[1279028640,250],[1279028700,230],[1279028760,229],[1279028820,229],[1279028880,246],[1279028940,255],[1279029000,263],[1279029060,258],[1279029120,231],[1279029180,146],[1279029240,144],[1279029300,145],[1279029360,130],[1279029420,131],[1279029480,122],[1279029540,111],[1279029600,113],[1279029660,111],[1279029720,112],[1279029780,111],[1279029840,113],[1279029900,159],[1279029960,187],[1279030020,185],[1279030080,183],[1279030140,181],[1279030200,180],[1279030260,180],[1279030320,177],[1279030380,177],[1279030440,175],[1279030500,174],[1279030560,174],[1279030620,172],[1279030680,173],[1279030740,171],[1279030800,163],[1279030860,144],[1279030920,146],[1279030980,144],[1279031040,142],[1279031100,135],[1279031160,141],[1279031220,"nan"],[1279031280,"nan"]]

So the resource we are calling is called 'sensor/c1411c6b4f9910bbbab09f145f8533b9' with 'd8a8ab8893ea73f768b66b45234b5c3a' as an access token. Query parameters are interval (hour) and unit (watt). We have already implemented a JSONP query option, which allows you to fetch this data from JS within any web page, process the array and visualize it in your JS graphing library of choice.

As Klaus mentioned, we will be migrating the current back-end API from XMLRPC to the REST one, resulting in a unified interface. This is scheduled for August. On top of this, we have a similar API running locally on the Fluksometer in a test setup. This allows you to visualize consumption in real-time (1s intervals).

We use Erlang/Webmachine [4] [5] for our server JSON/REST framework. The Flukso-specific code can be found on Github as well [6].

[1]: http://www.flukso.net/files/presentations/flukso.20100206.pdf
[2]: http://github.com/icarus75/flukso
[3]: http://www.flukso.net/content/jsonrest-api-released
[4]: http://bitbucket.org/justin/webmachine/wiki/Home
[5]: http://blog.therestfulway.com/2009/05/video-slideshow-introducing-webmachine.html
[6]: http://github.com/icarus75/flukso/tree/develop/server/api/flukso/

Best regards,

Bart Van Der Meerssche
Flukso
Nieuwstraat 104
B-3150 Wespelaar

tel: +32 479 28 14 48
skype/twitter: flukso
e-mail: bart.vandermeerssche at flukso.net
web: www.flukso.net

On 13 Jul 2010, at 12:21, Steffen Vogel wrote:

> Hello List,
> 
> i'm currently working on the new backend implementation as Justin
> mentioned. Some weeks ago, i completely took Justins code aside and
> started with a new object oriented backend. Its based on the
> Model-View-Controller pattern and is implemented with PHP 5.
> 
> After a week i realized that i spent 70% of my time on the database
> abstraction and the object relational mapper.
> So i kicked the DAL and ORM out of my code.
> Now im currently using doctrine [1] which is a fine library which will
> help us a lot.
> 
>> what's coming up?
>> not only do we want to replace the code, but we'll also do this:
>> - split the code into a "backend" and a "frontend"
>>  - backend:
>>    all the code that is not being accessed directly (i.e. works in the background, much like a db wrapper) is what we call the "backend"
>>    the backend is contacted by the the controller (resp. whatever counter device we might be using) and by the "frontend"
>>  - frontend:
>>    all the code that is being used for the visualization (i.e. the code the user might get to see) is called the "frontend"
>>    at present flo is working on a new browser visualization; although the frontend might also be code that feeds a fnordlicht [1] - much like a wattson [2] or a chumby [3] for a 24-7-in-home-visualization device that let's you know "en passent" what the current time^power consumption is
>> Steffen created a visual overview: http://static.steffenvogel.de/wp-content/uploads/2010/07/overview.png
> 
> At the moment, i'm soldering my 10 fnordlicht-minis ;) I'm curious to
> see them in action with volkszaehler.org/ethersex :)
> 
>> For a start some questions:
>> - what parameters do we need for the two APIs? (they will probably differ somewhat)
>> - how shall we document the current state of discussion? I think http://de.volkszaehler.wikia.com/wiki/Entwicklung/API would be the perfect place, wouldn't it?
> 
> Some weeks ago, i talked with flo about the API. Here's our first draft:
> http://de.volkszaehler.wikia.com/wiki/Entwicklung/API/Referenz
> 
> Unfortunately, i hadn't enough time to take a look on Barts API.
> Nevertheless, i think we could take Barts JSON Frontend API as an model
> for our API.
> 
>> One basic concept is going to change in that transition, BTW: so far we're logging every single request which was easy to implement on the controller side but not exactly brilliant and causing a lot of headaches. The new concept would be:
>> - define a resolution on the controller end (e.g. 1 minute, 15 minutes)
>> - fire a request only at that interval, including a "count" parameter (in case there was something happening in the last interval)
>> - the "count" (or whatevever we might be calling it) would be an absolute reading, not the number of pulses for the last interval; that makes the setup more robust against request loss
> 
> Now you finally convinced me ;) Especially the last point is quite
> important. How do you think to reset the controller (absolute value =
> 0). And how do we want to save this value (EEPROM vs. RAM?).
> 
> Regards, Steffen
> 
> [1] http://www.doctrine-project.org/
> 
> -- 
> Steffen Vogel
> Roonstraße 106
> Köln
> 
> Cell: +49 (176) 96978528
> Web: http://www.steffenvogel.de
> Mail & MSN: info at steffenvogel.de
> ICQ: 236033
> 
> _______________________________________________
> volkszaehler-dev mailing list
> volkszaehler-dev at lists.volkszaehler.org
> https://volkszaehler.org/mailman/listinfo/volkszaehler-dev