Coolkit (eWeLink) API Script in PHP

CoolKit (eWeLink) API Script in PHP
(Another donateWare script from MRE Software)

I had a need to read the temperature from my Sonoff TH20 temperature probe in my duck pond and post it on my weather website. I needed to run it as a simple cron job. Searching on the web, I found no example code written in PHP to accomplish this task and I had no desire to install Node JS and a big application just to read the temperature. So I set out to write a PHP script to do the job. The code on this page is the result of my efforts. Hopefully it will serve as an example for how to access this API using PHP.

This script uses version 2 of the CoolKit API and implements the OAuth 2.0 credential and token system. To use this you will need to register at https://dev.ewelink.cc/#/ and apply for developer status. Once approved you go to the console and create an app. You will be issued an app id and app secret. When creating an app you will also need to specify a redirect url. That url should point back to the location and name of this script on your website. Once you have those credentials you edit the variables in the script to use them. FYI: I named my script th20oa2.php and that is in the $redir variable in the code. Change it if you want.

How it works: After editing your credentials, redirection url, and device id you install the script on your website. Make sure the redirection url on the CoolKit developer console matches the full url to the script. This is a security measure and the authentication will fail without it. The first thing you will need to do is log into the script using a web browser. You do this by accessing the script with the login parameter. example: https://yourdomain.com/th20oa2.php?login=1 When you do this the script will return a link to click. Clicking the link will take you to the OAuth 2.0 login page where you use your normal eWeLink cellphone app credentials. Once you hit the login button, CoolKit will send the authorization code back to the script on your website. The script will process the code and obtain the access and refresh tokens needed to make API calls. The tokens are valid for 30 days and will be stored in a file. The good news is that the tokens can be refreshed without requiring another manual log in. This script checks the expiration date and refreshes the tokens after 28 days so the script can operate indefinitely without requiring a human log in operation. Once you are logged in and have the tokens the script can read your devices. In my case, all I needed to do was read the temperature of one device but other users may want to do things like control devices etc. Those operations are explained in the API documentation. The hard part of using this API is logging in, getting, and refreshing the tokens. I am publishing this to demonstrate how that is done with PHP. It took me several hours to figure it all out so maybe this will save you some time!

Developer's tip: The script has to be live on the Internet to get the tokens. Once the tokens are obtained and saved to a file on your website, you can copy that token file to your local development computer environment and use the tokens for 28 days. When they refresh they will need to be synced again. This allows you to work on the script locally.

Check the update date/time on the second line of the script to insure that you have the latest version.

This code is for informational purposes only.
USE AT YOUR OWN RISK

ENJOY!

<?php // This script gets the current temperature from my TH20 using the eWelink API // Updated 08/22/2024 @ 11:01 AM CST //error_reporting(0); // uncomment if you want to hide any warnings $appid = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // your app id as registered in the coolkit developer console $secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // your app secret as issued in the coolkit developer console $redir = 'https://yourdomain.com/th20oa2.php'; // This must be the full url to this script on your server and referenced in the developer console $myDeviceId = '1001e2233e'; // the device id you want want to read. In this case it is my TH20 $email = "you@yourdomain.com"; // Set to the email address to send triggered reports // Probably no need to edit below this line unless you want to use an API server not in the USA. $url = "https://us-apia.coolkit.cc"; // the url of the coolkit USA API $authUrl = 'https://c2ccdn.coolkit.cc/oauth/index.html'; // the authorization url for the API $token_file = 'th20_token.txt'; // this is the name of the file where tokens are stored $grant = 'authorization_code'; // this is the only grant type supported by the api - do not change $path = __DIR__ . '/'; // This is needed when running as a cron job. // To initially login go to the script on your server and add ?login=1 to the url ie: https://domain/path/th20oa2.php?login=1 // This block builds the login url and displays a link in the user's browser to be clicked if(isset($_GET['login'])){ // if this is a login request execute the login sequence /* $login = $_GET['login']; // one can test this login value and limit the procedure to only authorized values if desired. if($login != 'an authorized value'){ echo 'You are not authorized to login to this app.'; email_me('Log-in attempt failed with: ' . $login); exit; } */ $seq = time() * 1000; // current time in milliseconds, well close enuf anyway $auth = base64_encode(hash_hmac('SHA256', $appid.'_'.$seq, $secret, true)); $state = '1234'; $myauthUrl = "${authUrl}?state=${state}&clientId=${appid}&authorization=${auth}&seq=${seq}&redirectUrl=${redir}&nonce=zt123456&grantType=${grant}"; echo 'The page linked below is the OAuth 2.0 login for the eWeLink API. Use the same credentials as your eWeLink phone app. '; echo '<a href="'.$myauthUrl.'">Click here to open the user OAuth login page.</a>'; //This displays a loaded link for the user to click exit; } // This block responds to an authorization code return to get and save the tokens and expiration times. if(isset($_GET['code'])){ $code = $_GET['code']; //$region = $_GET['region']; // to select the best API server - not used in this script //$state = $_GET['state']; // to verify it matches the state sent - not used in this script $appDetails = ['code' => $code, 'redirectUrl' => $redir, 'grantType' => $grant]; $jsonData = json_encode($appDetails); $sign = base64_encode(hash_hmac('SHA256', $jsonData, $secret, true)); $header = array('x-ck-appid:' . $appid, 'Authorization: Sign ' . $sign, 'Content-Type: application/json', 'Content-Length: ' . strlen($jsonData)); $myurl = $url . '/v2/user/oauth/token'; $response = curl_it('POST', $myurl, $jsonData, $header); // use cUrl to post it if(!$response) echo 'cUrl returned error: '.curl_errno($ch); else{ $authbody = json_decode($response, true); if($authbody['error'] == 0){ echo 'Response from server saved to file: '.$response; file_put_contents($path.$token_file, $response); // save all the tokens still in json format. } else echo 'Get tokens failed.'; } exit; } // This is what executes if login or code is not in the url parameters. It refreshes tokens if needed. $tokens = file_get_contents($path.$token_file); $authbody = json_decode($tokens, true); // tokens are stored in json format $AT = $authbody['data']['accessToken']; $ATXT = $authbody['data']['atExpiredTime']; $RT = $authbody['data']['refreshToken']; $RTXT = $authbody['data']['rtExpiredTime']; if($ATXT - (time() * 1000) <= 1728000000){ // Token is good for 30 days. I refresh it every 28 days $myurl = $url . '/v2/user/refresh'; $appDetails = ['rt' => $RT]; $jsonData = json_encode($appDetails); $sign = base64_encode(hash_hmac('SHA256', $jsonData, $secret, true)); $header = array('x-ck-appid:' . $appid, 'Authorization: Sign ' . $sign, 'Content-Type: application/json', 'Content-Length: ' . strlen($jsonData)); $response = curl_it('POST', $myurl, $jsonData, $header); // use cUrl to post it if(!$response) email_me('TH20 error - Refresh tokens failed with curl error. Need to log in again.'); else{ $authbody = json_decode($response, true); if($authbody['error'] == 0){ $AT = $authbody['data']['at']; // new access token $RT = $authbody['data']['rt']; // new refresh token $ATXT = time()*1000 + 2592000000; // add 30 days to the present time $RTXT = time()*1000 + 2592000000; // add 30 days to the present time // Build a new string to write to the file. They should have returned it the same way as the initial token fetch! $response = '{"error":0,"msg":"","data":{"accessToken":"'.$AT.'","atExpiredTime":'.$ATXT.',"refreshToken":"'.$RT.'","rtExpiredTime":'.$RTXT.'}}'; echo 'Response from server saved to file: '.$response.' '; // for debugging file_put_contents($path.$token_file, $response); // save all the tokens still in json format. } else{ echo 'Refresh tokens failed.'; email_me('TH20 error - Refresh tokens failed. Need to log in again.'); } } } // Start of process to get the data. This gets only my specific device $myDeviceId $tokens = file_get_contents($path.$token_file); // Even if refresh fails the old token may still work so just get it again. $authbody = json_decode($tokens, true); // tokens are stored in json format $AT = $authbody['data']['accessToken']; // the access token is all that is needed for authorization Bearer $error = false; //This detects any errors along the way $device_array = [['itemType' => 1, 'id' => $myDeviceId]]; // this should be an array of devices you want to retrieve - see the docs // To get up to 10 things add more arrays. 2 for example [['itemType' => 1, 'id' => $myDeviceId], ['itemType' => 1, 'id'=>'10003eba99']] $devList = GetSpecificDevices($device_array); // call the function to retrieve the data // Now find my specific device current temperature. To see the whole array structure examine the function code if($devList){ $temp = $devList['data']['thingList']['0']['itemData']['params']['currentTemperature']; if($temp != 'unavailable') $temp = number_format(round($temp * 9/5 + 32, 1),"1"); // if probe working then convert to F and format else $error = true; if(!$devList['data']['thingList']['0']['itemData']['online']) $error = true; // check that device is online if(!$temp) $error = true; } else $error = true; if($error) $temp = 'NAN'; // if it failed return Not Available Now (NAN) file_put_contents($path.'th20.txt', $temp); // write the result to a text file echo 'The TH20 temperature is: ' . $temp.' degrees Fahrenheit '; $devList = GetAllDevices(); // This is just a bonus feature for fun showing your device list. - call the function to retrieve the data if($devList){ echo " A list of all of your found devices appears below. If you don't see all your devices in the list it is probably because eWeLink limits what manufacturers it shows. I have found that if you use the explicit device ID of even something that doesn't appear in the list you can still work with it."; echo '<pre>'; print_r($devList); echo '</pre>';// This outputs a nice array structure } else echo 'Get device list failed'; // email_me($temp); // if you want to test cron job uncomment this and get an email every time it executes ///FUNCTIONS DEFINED BELOW/// function GetSpecificDevices($device_array){ // This function returns the specific device list as a json decoded PHP array global $url, $appid, $AT; $appDetails = ['thingList' => $device_array]; $jsonData = json_encode($appDetails); $myurl = $url . '/v2/device/thing'; $header = array('x-ck-appid:' . $appid, 'Content-Type: application/json','Accept: */*','Authorization: Bearer ' . $AT); $response = curl_it('POST', $myurl, $jsonData, $header); if(!$response) return false; // On failure this function returns false. else $devList = json_decode($response, true); // decode into a PHP array if($devList['error'] == 0){ // echo '<pre>'; print_r($devList); echo '</pre>'; // uncomment this to see the array structure of the response when debugging/developing return $devList; // On success this function returns a json decoded array. } else return false; // On failure this function returns false. } //////////////////////// function GetAllDevices(){ // This function returns the whole device list as a json decoded PHP array global $url, $appid, $AT; $params = "lang=en"; $myurl = $url . '/v2/device/thing?'.$params; $header = array('x-ck-appid:' . $appid, 'Content-Type: application/json','Accept: */*','Authorization: Bearer ' . $AT); $response = curl_it('GET', $myurl, '', $header); if(!$response) return false; // On failure this function returns false. else $devList = json_decode($response, true); // decode into a PHP array if($devList['error'] == 0){ // echo '<pre>'; print_r($devList); echo '</pre>'; // uncomment this to see the array structure of the response when debugging/developing return $devList; // On success this function returns a json decoded array. } else return false; // On failure this function returns false. } //////////////////////// function curl_it($method, $myurl, $data, $header){ $ch = curl_init($myurl); curl_setopt($ch, CURLOPT_TIMEOUT, 30); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method); if($method == 'POST') curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_HTTPHEADER, $header); $response = curl_exec($ch); if(!$response || curl_errno($ch)) $response = false; curl_close($ch); return $response; } //////////////////////// function email_me($message){ global $email; $headers = "From: " . $email . "\r\n"; $subject = "TH20 cron job."; mail($email, $subject, $message, $headers) ; } ?>

If you find this code of value, donate a little to the cause. Think of the time you just saved!

USE AT YOUR OWN RISK!

Questions / Comments? Email me.