Suppose you have a telldus.net, a Telldus account, at least one sensor and
Internett connection to the web;
To connect to the Telldus API, you need some security keys;
You will get your keys here: https://api.telldus.com/keys/index
The 4 keys looks like this :
PUBLIC_KEY = 'FExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; (Replace the strings by your own)
PRIVATE_KEY = 'ZUxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
TOKEN = '6cxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
TOKEN_SECRET= '0ccxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
(Don’t even think of ”key in” these values; Use copy/past)
PUBLIC_KEY is in some places also called ” ConsumerKey”
PRIVATE_KEY is in some places also called ” ConsumerSecret”
You will need some Telldus URL’s:
API_URL = 'https://api.telldus.com'; { Use https://.... in production}
ACCESS_TOKEN = '/oauth/accessToken'; {Not used in this example}
REQUEST_TOKEN = '/oauth/requestToken'; {Not used in this example }
AUTHORIZE_TOKEN= '/oauth/authorize'; {Not used, in this example only web login}
REQUEST_XML = '/xml'; { Get response as XML}
REQUEST_JSON = '/json'; { Get response as JSON }
SENSOR_LIST = '/sensors/list'; {Get list of your sensos, and last sensor values}
DEVICES_LIST = '/devices/list'; {Get list of devices; Not used in this example}
SENSOR_INFO = '/sensor/info'; {Get info and value of one sensor; Not used in this exampler}
+ suppose there are some more.
Then you will need a ”oAuth” program. Telldus is using OAuth 1.0
(There are some links abouth oAuth in the bottom of this dokument.)
The oAuth program need the 4 security key’s and an Url :
As you have all 4 security key’s, you don’t need all URL’s, just use:
To get a list of all sensors:
URL=API_URL + REQUEST_XML + SENSOR_LIST or
URL=API_URL + REQUEST_JSON + SENSOR_LIST
To get info of one sensor:
URL=API_URL + REQUEST_XML + SENSOR_INFO or
URL=API_URL + REQUEST_JSON + SENSOR_INFO
(Put the sensor number in the oAuth.SendBody )
Important:
The OAuth 1.0 Protocol expect the 4 security key’s in ASCII (or Ansi)
As most OS these days use utf8, convert like this:
ConsumerKey =UTF8ToAnsi(PUBLIC_KEY);
ConsumerSecret = UTF8ToAnsi(PRIVATE_KEY);
AuthToken = UTF8ToAnsi(TOKEN);
AuthSecret = UTF8ToAnsi(TOKEN_SECRET);
Build the send (In some ”pseudocode”)
You have to supply with some parameters (to tell Telldus API what you want in return):
PARAM:='includeIgnored=0&'+ 'includeValues=1&' + 'includeScale=0';
or just: PARAM:= 'includeValues=1'
oAuth.CallBackURL = '""; (no value)
oAuth.FallBackOOB = False;
Typical request,:
oAuth.SendBody := PARAM
oAuth.URL := API_URL + REQUEST_XML + SENSOR_LIST
If (oAuth.OAuthHTTPMethod('POST', URL) = 200) …..
If you recive 200 the request is OK;
The oAuth will send to Telldus a string like this (as XML or JSON):
https://api.telldus.com /xml /sensors/list or
https://api.telldus.com /json /sensors/list
If the request is accepted, Telldus API will respond with a string in the ReceivedBody:
XML:
<?xml version="1.0" encoding="utf-8" ?>
<sensors>
<sensor id="9999999" name=" RainSensor " lastUpdated="1422825359"
ignored="0" client="9999999" clientName="Home" online="1" editable="1" battery="254" rrate="0.0" rtot="262.1" />
</sensors>
JSON:
{"sensor":[{"id":"9999999","name":"RainSensor","lastUpdated":1422825359,
"ignored":0,"client":"9999999","clientName":"Home","online":"1","editable":1,"battery":254,"rrate":"0.0","rtot":"262.1"}]}
Info fields:
id: Sensor id number. (Not visible in http://www.livetelldus.com)
name: Sensor name, as in http://www.livetelldus.com, ”MySensors”
lastUpdated: Last update time in Unix format. (Seconds since 1970.1.1) Seems to be UTC time (GMT).
ignored: http://www.livetelldus.com, MySensors -> Edit -> show in list.
Client: Client number (Not visible in http://www.livetelldus.com)
clientName: Name from http://live.telldus.com -> My Locations
online: 1=Sensor is online;
editable: (? No idea)
battery: Not in use, allways 254, may be used in the future.
Possible value fields and format in recived string:
temp 0.0 (ºC or F, depending on sensor)
humidity 00 (%)
rrate 0.0 (mm, Don’t know exactly how it works but seems ok in graph)
rtot 0.0 (mm, accumulated since last start of sensor)
wdir 0.0 (Wind direction)
wgust 0.0 (Wind gust)
wavg 0.0 ( Average of wind speeds -)
All is recived as string, no decimal values.
Value fields may be combined like this:
temp
temp and humidity
rrate and rtot
wdir, wgust and wavg
Sensors not defined by Telldus may look like temp and humidity.
…………………..
The OAuth 1.0a Protocol has some more possibilities but should work.
The OAuth2 Protocol is totally different and will not work with Telldus API.
Links:
The OAuth 1.0 Protocol: http://tools.ietf.org/html/rfc5849
The OAuth 1.0 guide covers the protocol as defined by RFC 5849: http://hueniverse.com/oauth/
OAuth, Send secure authorized requests to the Twitter API: https://dev.twitter.com/oauth
How to use Telldus API
Moderator: Telldus
How to use Telldus API
Last edited by arneolav on Sat Feb 07, 2015 10:23 am, edited 3 times in total.
Telldus API with Pascal / Delphi / Lazarus
After a lot of problems I succeded to get values from Telldus API using a Pascal oAuth procedure with all code in Lazarus (Delphi/pascal)
and as described above.
The main problem turned out to be missing UTF8ToAnsi convert of the security keys.
A simple task when I found it…
Download the pascal oAuth:
https://bitbucket.org/reiniero/fpctwit last update: reiniero-fpctwit-5589ff949b4c.zip/
The download includ all you need of oAuth and Synapse.
The included Synapse is a special version.
Don’t try to use the default Synapse as i will not work.
I’m using the downloaded oAuth.pas ”as is”, not changed anything.
Tested in windows 8.1, but as all is written in Lazarus (pascal) this should work in *nix as well.
In the following, some code you need. Not complete, but should help a lot.
- program GetTellSensor;
- unit Telldus_API
- unit ConnectAPI;
Lazarus homepage: http://www.lazarus.freepascal.org/
and as described above.
The main problem turned out to be missing UTF8ToAnsi convert of the security keys.
A simple task when I found it…
Download the pascal oAuth:
https://bitbucket.org/reiniero/fpctwit last update: reiniero-fpctwit-5589ff949b4c.zip/
The download includ all you need of oAuth and Synapse.
The included Synapse is a special version.
Don’t try to use the default Synapse as i will not work.
I’m using the downloaded oAuth.pas ”as is”, not changed anything.
Tested in windows 8.1, but as all is written in Lazarus (pascal) this should work in *nix as well.
In the following, some code you need. Not complete, but should help a lot.
- program GetTellSensor;
- unit Telldus_API
- unit ConnectAPI;
Lazarus homepage: http://www.lazarus.freepascal.org/
Last edited by arneolav on Mon Feb 02, 2015 10:25 am, edited 7 times in total.
Telldus API with Pascal / Delphi / Lazarus
Call from this program:
program GetTellSensor;
{$mode objfpc}{$H+}
{$apptype gui}
uses
{$IFDEF UNIX}{$IFDEF UseCThreads}
cthreads,
{$ENDIF}{$ENDIF}
Classes, SysUtils, CustApp
{ you can add units after this }
, Telldus_Api ;
type
{ TMyApplication }
TMyApplication = class(TCustomApplication)
protected
procedure DoRun; override;
public
constructor Create(TheOwner: TComponent); override;
destructor Destroy; override;
procedure WriteHelp; virtual;
end;
{ TMyApplication }
procedure TMyApplication.DoRun;
var
ErrorMsg: String;
begin
begin
{ add your program here }
with TGetValues.Create do
try
MainProc; //GetValues.MainProc 24/7;
finally
Free;
end;
Terminate;
end;
constructor TMyApplication.Create(TheOwner: TComponent);
begin
inherited Create(TheOwner);
StopOnException:=True;
end;
destructor TMyApplication.Destroy;
begin
inherited Destroy;
end;
procedure TMyApplication.WriteHelp;
begin
{ add your help code here }
writeln('Usage: ',ExeName,' -h');
end;
//----------------- main starts here
const
var
Application: TMyApplication;
begin
Application:=TMyApplication.Create(nil);
Application.Title:='Get Sensor Values';
Application.Name:= 'GetSensVal';
Application.Run;
Application.Free;
end.
program GetTellSensor;
{$mode objfpc}{$H+}
{$apptype gui}
uses
{$IFDEF UNIX}{$IFDEF UseCThreads}
cthreads,
{$ENDIF}{$ENDIF}
Classes, SysUtils, CustApp
{ you can add units after this }
, Telldus_Api ;
type
{ TMyApplication }
TMyApplication = class(TCustomApplication)
protected
procedure DoRun; override;
public
constructor Create(TheOwner: TComponent); override;
destructor Destroy; override;
procedure WriteHelp; virtual;
end;
{ TMyApplication }
procedure TMyApplication.DoRun;
var
ErrorMsg: String;
begin
begin
{ add your program here }
with TGetValues.Create do
try
MainProc; //GetValues.MainProc 24/7;
finally
Free;
end;
Terminate;
end;
constructor TMyApplication.Create(TheOwner: TComponent);
begin
inherited Create(TheOwner);
StopOnException:=True;
end;
destructor TMyApplication.Destroy;
begin
inherited Destroy;
end;
procedure TMyApplication.WriteHelp;
begin
{ add your help code here }
writeln('Usage: ',ExeName,' -h');
end;
//----------------- main starts here
const
var
Application: TMyApplication;
begin
Application:=TMyApplication.Create(nil);
Application.Title:='Get Sensor Values';
Application.Name:= 'GetSensVal';
Application.Run;
Application.Free;
end.
Last edited by arneolav on Mon Feb 02, 2015 9:15 am, edited 1 time in total.
Telldus API with Pascal / Delphi / Lazarus
Create a Unit Telldus_API; and use this proc:
procedure TGetValues.GetValuesFromTelldus;
var PARAM: string;
begin
CreateOauth;
PARAM:='includeIgnored=0&'+ 'includeValues=1&' + 'includeScale=0';
if FSensor.Request(REQUEST_XML, SENSOR_LIST, PARAM ) then
begin
SaveInputString((FSensor.GetBody), FilePath // save sensorlist to a file
SaveSensorValues(FilePath); // save values. You may write your own or ask me
end
else
WriteSensorValues( 'Sorry, connection attempt failed.', sSensorDirectory +'\'+'Errlog' + '.txt');
end;
Youll need some more code here...
procedure TGetValues.GetValuesFromTelldus;
var PARAM: string;
begin
CreateOauth;
PARAM:='includeIgnored=0&'+ 'includeValues=1&' + 'includeScale=0';
if FSensor.Request(REQUEST_XML, SENSOR_LIST, PARAM ) then
begin
SaveInputString((FSensor.GetBody), FilePath // save sensorlist to a file
SaveSensorValues(FilePath); // save values. You may write your own or ask me
end
else
WriteSensorValues( 'Sorry, connection attempt failed.', sSensorDirectory +'\'+'Errlog' + '.txt');
end;
Youll need some more code here...
Last edited by arneolav on Mon Feb 02, 2015 9:23 am, edited 3 times in total.
Telldus API with Pascal / Delphi / Lazarus
Connect to the oAuth this way:
unit ConnectAPI;
// Follow oauth includes, including setting test compiler define:
{$i oauth.inc}
interface
uses
Classes, SysUtils, oauth1;
type
{ TSensor }
TSensor = class(TObject)
private
{ private declarations }
FOauth: TOAuth1; //Used for authorization & HTTP/HTTPS communication
public
{ public declarations }
procedure SetURL(AValue: string);
procedure SetConsumerKey(AValue: string);
procedure SetConsumerSecret(AValue: string);
procedure SetAuthToken(AValue: string);
procedure SetAuthSecret(AValue: string);
function Request(const REQUEST_URI, REQUEST_URL, SendBody: string): Boolean;
function GetBody: String;
constructor Create;
destructor Destroy; override;
end;
var
API_URL: String;
implementation
procedure TSensor.SetAuthSecret(AValue: string);
begin
FOauth.AuthSecret := AValue;
end;
procedure TSensor.SetAuthToken(AValue: string);
begin
FOauth.AuthToken := AValue;
end;
procedure TSensor.SetConsumerKey(AValue: string);
begin
FOAuth.ConsumerKey := AValue;
end;
procedure TSensor.SetConsumerSecret(AValue: string);
begin
FOAuth.ConsumerSecret := AValue;
end;
procedure TSensor.SetURL(AValue: string);
begin
API_URL := AValue;
end;
function TSensor.Request(const REQUEST_URI, REQUEST_URL, SendBody: string): Boolean;
var URL: string;
begin
FOauth.SendBody := SendBody;
URL := API_URL + REQUEST_URI + REQUEST_URL;
Result := (FOauth.OAuthHTTPMethod('POST', URL) = 200);
end;
function TSensor.GetBody: String;
begin
Result:=FOAuth.ReceivedBody;
end;
constructor TSensor.Create;
begin
inherited Create;
FOauth := TOAuth1.Create;
FOAuth.BaseURL := API_URL;
FOAuth.AccessTokenResource := '/oauth/accessToken'; FOAuth.AcquirePINPath:='/oauth/authorize?oauth_token=';
FOAuth.RequestTokenResource := '/oauth/requestToken'; FOAuth.RequestTokenResource := '/oauth/request_token';
FOauth.CallBackURL := '';
FOAuth.FallBackOOB := False;
end;
destructor TSensor.Destroy;
begin
FOauth.Destroy;
inherited Destroy;
end;
end.
unit ConnectAPI;
// Follow oauth includes, including setting test compiler define:
{$i oauth.inc}
interface
uses
Classes, SysUtils, oauth1;
type
{ TSensor }
TSensor = class(TObject)
private
{ private declarations }
FOauth: TOAuth1; //Used for authorization & HTTP/HTTPS communication
public
{ public declarations }
procedure SetURL(AValue: string);
procedure SetConsumerKey(AValue: string);
procedure SetConsumerSecret(AValue: string);
procedure SetAuthToken(AValue: string);
procedure SetAuthSecret(AValue: string);
function Request(const REQUEST_URI, REQUEST_URL, SendBody: string): Boolean;
function GetBody: String;
constructor Create;
destructor Destroy; override;
end;
var
API_URL: String;
implementation
procedure TSensor.SetAuthSecret(AValue: string);
begin
FOauth.AuthSecret := AValue;
end;
procedure TSensor.SetAuthToken(AValue: string);
begin
FOauth.AuthToken := AValue;
end;
procedure TSensor.SetConsumerKey(AValue: string);
begin
FOAuth.ConsumerKey := AValue;
end;
procedure TSensor.SetConsumerSecret(AValue: string);
begin
FOAuth.ConsumerSecret := AValue;
end;
procedure TSensor.SetURL(AValue: string);
begin
API_URL := AValue;
end;
function TSensor.Request(const REQUEST_URI, REQUEST_URL, SendBody: string): Boolean;
var URL: string;
begin
FOauth.SendBody := SendBody;
URL := API_URL + REQUEST_URI + REQUEST_URL;
Result := (FOauth.OAuthHTTPMethod('POST', URL) = 200);
end;
function TSensor.GetBody: String;
begin
Result:=FOAuth.ReceivedBody;
end;
constructor TSensor.Create;
begin
inherited Create;
FOauth := TOAuth1.Create;
FOAuth.BaseURL := API_URL;
FOAuth.AccessTokenResource := '/oauth/accessToken'; FOAuth.AcquirePINPath:='/oauth/authorize?oauth_token=';
FOAuth.RequestTokenResource := '/oauth/requestToken'; FOAuth.RequestTokenResource := '/oauth/request_token';
FOauth.CallBackURL := '';
FOAuth.FallBackOOB := False;
end;
destructor TSensor.Destroy;
begin
FOauth.Destroy;
inherited Destroy;
end;
end.