README.rst 4.55 KB
Newer Older
Cédric's avatar
Cédric committed
1
2
3
4
5
6
7
++++++++++
Grenouille
++++++++++

Presentation
============

Cédric's avatar
Cédric committed
8
Grenouille is an online service for weather data.
Cédric's avatar
Cédric committed
9
All data can be obtained in JSON and displayed on a map.
10
The Web application is based on `Flask <http://flask.pocoo.org>`_.
Cédric's avatar
Cédric committed
11

Cédric's avatar
Cédric committed
12
An example of a client for the Yocto-Meteo sensor
13
14
(connected to a `Raspberry Pi <http://www.raspberrypi.org>`_)
is provided (inspired from `this code <https://github.com/tarekziade/grenouille>`_).
Cédric's avatar
Cédric committed
15
Of course you can implement your own client with the API documentation.
Cédric's avatar
Cédric committed
16

17
The official instance is running `here <https://petite-grenouille.herokuapp.com>`_.
Cédric's avatar
Cédric committed
18
19
20
21
22
23
24

Usage
=====

Deployment
----------

Cédric's avatar
Cédric committed
25
The platform can be deployed on Heroku or on a traditional server.
Cédric's avatar
Cédric committed
26

Cédric's avatar
Cédric committed
27
28
After installation, you will be able to connect with the email
*root@grenouille.localhost* and the password *password*.
Cédric's avatar
Cédric committed
29
30
31
32
33
34

Deploying the application on Heroku
'''''''''''''''''''''''''''''''''''

.. code:: bash

35
    $ git clone https://github.com/cedricbonhomme/Grenouille
Cédric's avatar
Cédric committed
36
37
38
    $ cd grenouille
    $ heroku create
    $ heroku addons:add heroku-postgresql:dev
Cédric's avatar
Cédric committed
39
    $ heroku config:set HEROKU=1
Cédric's avatar
Cédric committed
40
    $ git push heroku master
Cédric's avatar
Cédric committed
41
42
    $ heroku run init
    $ heroku ps:scale web=1
Cédric's avatar
Cédric committed
43

Cédric Bonhomme's avatar
Cédric Bonhomme committed
44
Deploying the application on a traditional server
Cédric Bonhomme's avatar
Cédric Bonhomme committed
45
'''''''''''''''''''''''''''''''''''''''''''''''''
Cédric Bonhomme's avatar
Cédric Bonhomme committed
46
47
48

.. code:: bash

49
    $ git clone https://github.com/cedricbonhomme/Grenouille
Cédric Bonhomme's avatar
Cédric Bonhomme committed
50
    $ cd grenouille
Cédric's avatar
Cédric committed
51
    $ poetry install
Cédric's avatar
Cédric committed
52
53
54
55
56
57
58
59
    $ cp conf/conf.cfg-sample conf/conf.cfg

If you want to use PostgreSQL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: bash

    $ sudo apt-get install postgresql postgresql-server-dev-9.3 postgresql-client
Cédric Bonhomme's avatar
Cédric Bonhomme committed
60
    $ sudo -u postgres createuser
Cédric's avatar
Cédric committed
61
62
63
64
    Enter name of role to add: username
    Shall the new role be a superuser? (y/n) n
    Shall the new role be allowed to create databases? (y/n) y
    Shall the new role be allowed to create more new roles? (y/n) n
Cédric Bonhomme's avatar
Cédric Bonhomme committed
65
    $ createdb grenouille
Cédric Bonhomme's avatar
Cédric Bonhomme committed
66
    $ sudo -u postgres psql
Cédric Bonhomme's avatar
Cédric Bonhomme committed
67
68
69
    postgres=# ALTER USER username WITH ENCRYPTED PASSWORD 'password';
    postgres=# GRANT ALL PRIVILEGES ON DATABASE grenouille TO username;
    postgres=# \q
Cédric's avatar
Cédric committed
70
71
72
73
74
75

Edit the configuration file with the line:

.. code:: cfg

    [database]
76
    uri = postgresql://username:password@127.0.0.1:5433/grenouille
Cédric's avatar
Cédric committed
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

If you want to use SQLite
~~~~~~~~~~~~~~~~~~~~~~~~~

Just edit the configuration file with the line:

.. code:: cfg

    [database]
    uri = sqlite+pysqlite:///grenouille.db


Finally:

.. code:: bash

Cédric's avatar
Cédric committed
93
    $ poetry shell
94
95
96
97
    $ python db_create.py
    $ python runserver.py
     * Running on http://0.0.0.0:5000/
     * Restarting with reloader
Cédric Bonhomme's avatar
Cédric Bonhomme committed
98

99
100
101
102
103
104
105

Web services
------------

Send measures
'''''''''''''

Cédric's avatar
Cédric committed
106
107
This example shows how to send measures from a station to the platform.

108
109
.. code:: python

Cédric's avatar
Cédric committed
110
    >>> url = "https://petite-grenouille.herokuapp.com/weather.json/"
Cédric Bonhomme's avatar
Cédric Bonhomme committed
111
112
    >>> headers = {'Content-type': 'application/json', 'Accept': 'application/json'}
    >>> data = {'pression': 1023, 'api_key': 'VDZCF0aa1nUazxbCX2q01FKRWALxdIzCMNmg', 'temperature': 20, 'station_id': 2, 'humidity': 81}
113
114
115
    >>> r = requests.post(url, data=json.dumps(data), headers=headers, auth=('your-email@example.com', 'password'))
    >>> print r.content
    {
Cédric's avatar
Cédric committed
116
        "result": "OK"
117
118
    }

119
120
121
122
123
You can use the provided client:

.. code:: bash

    $ ./grenouillecli.py --email your-email@example.com --password password --api-key qGWjgIybd1i8uh89o5 --station 4 --temperature 25.7 --pression 980 --humidity 84
Cédric's avatar
Cédric committed
124
125
126
    {
        "result": "OK"
    }
127

Cédric's avatar
Cédric committed
128
129
130
131
132
133
134
135
136
137
138
139
140

Get measures
''''''''''''

By country:

.. code:: bash

    $ curl https://petite-grenouille.herokuapp.com/weather.json/?q=FR
    {
        "result": [
            {
            "coord": {
Cédric's avatar
Cédric committed
141
                "lat": 49.115558,
Cédric's avatar
Cédric committed
142
                "lon": 6.175635
Cédric's avatar
Cédric committed
143
144
145
146
            },
            "country": "FR",
            "date": "Sat, 05 Apr 2014 21:17:43 GMT",
            "id": 1,
Cédric's avatar
Cédric committed
147
            "main": {
Cédric's avatar
Cédric committed
148
149
                "humidity": 84.0,
                "pression": 980.0,
Cédric's avatar
Cédric committed
150
                "temperature": 25.7
Cédric's avatar
Cédric committed
151
            },
Cédric's avatar
Cédric committed
152
            "name": "Metz"
Cédric's avatar
Cédric committed
153
            },
Cédric's avatar
Cédric committed
154
155
            {
            "coord": {
Cédric's avatar
Cédric committed
156
                "lat": 45.649781,
Cédric's avatar
Cédric committed
157
                "lon": 0.153623
Cédric's avatar
Cédric committed
158
159
160
161
            },
            "country": "FR",
            "date": "Thu, 03 Apr 2014 05:34:00 GMT",
            "id": 5,
Cédric's avatar
Cédric committed
162
            "main": {
Cédric's avatar
Cédric committed
163
164
                "humidity": 82.0,
                "pression": 980.0,
Cédric's avatar
Cédric committed
165
                "temperature": 23.2
Cédric's avatar
Cédric committed
166
            },
Cédric's avatar
Cédric committed
167
168
169
170
171
172
            "name": "Angoul\u00eame"
            }
        ]
    }


Cédric's avatar
Cédric committed
173
174
175
176

License
=======

177
`Grenouille <https://github.com/cedricbonhomme/Grenouille>`_
Cédric's avatar
Cédric committed
178
is under the `GNU Affero General Public License version 3 <https://www.gnu.org/licenses/agpl-3.0.html>`_.
Cédric's avatar
Cédric committed
179

180

Cédric's avatar
Cédric committed
181
182
183
Contact
=======

184
`My home page <https://www.cedricbonhomme.org>`_.