index.html
15.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>hueplusplus: Documentation for the hueplusplus library</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">hueplusplus
 <span id="projectnumber">1.0.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Documentation for the hueplusplus library </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><ul><li class="level2"><a href="#autotoc_md6">Features</a></li>
<li class="level2"><a href="#autotoc_md7">Compatibility</a></li>
<li class="level2"><a href="#autotoc_md8">How to use</a><ul><li class="level3"><a href="#autotoc_md9">Searching for Bridges</a></li>
<li class="level3"><a href="#autotoc_md10">Authenticate Bridges</a></li>
<li class="level3"><a href="#autotoc_md11">Controlling lights</a></li>
</ul>
</li>
<li class="level2"><a href="#autotoc_md12">Build and install</a><ul><li class="level3"><a href="#autotoc_md13">Basic installation</a></li>
<li class="level3"><a href="#autotoc_md14">Advanced usage</a></li>
<li class="level3"><a href="#autotoc_md15">Running tests</a></li>
</ul>
</li>
<li class="level2"><a href="#autotoc_md16">Other pages</a></li>
</ul>
</ul>
</div>
<div class="textblock"><p>A simple and easy to use library for Philips Hue Lights.</p>
<ul>
<li>find bridges with SSDP or set an ip manually</li>
<li>all common light functions (brightness, color, temperature)</li>
<li>extended alert() functions, which alert in a specific color (good for notifications)</li>
<li>supports sensors, rules, groups, scenes and schedules</li>
<li>streaming with entertainment mode</li>
<li>documented with doxygen</li>
<li>tested with google test, google mock and gcov/lcov</li>
</ul>
<ul>
<li>Linux</li>
<li>Windows</li>
<li>MacOS</li>
<li>Espressif ESP32 SDK & Arduino</li>
</ul>
<p><a class="el" href="getting-started.html">Getting started</a> </p>
<p>To start searching for a Hue Bridge you will need to choose an IHttpHandler and create one. The options are a <a class="el" href="classhueplusplus_1_1_win_http_handler.html">WinHttpHandler</a> (for windows) or a <a class="el" href="classhueplusplus_1_1_lin_http_handler.html">LinHttpHandler</a> (for linux or linux-like).</p>
<p>Then create a <a class="el" href="classhueplusplus_1_1_bridge_finder.html">BridgeFinder</a> object with the handler. The handler is needed, because it tells the finder which functions to use to communicate with a bridge or your local network. After that you can call <a class="el" href="classhueplusplus_1_1_bridge_finder.html#a86cce17f26187a97547a44fab8c920a1">findBridges()</a>, which will return a vector containing the ip and mac address of all found Bridges. </p><div class="fragment"><div class="line"> <span class="comment">// For windows use std::make_shared<hueplusplus::WinHttpHandler>();</span></div><div class="line"> <span class="keyword">auto</span> handler = std::make_shared<hueplusplus::LinHttpHandler>();</div><div class="line"> <a class="code" href="classhueplusplus_1_1_bridge_finder.html">hueplusplus::BridgeFinder</a> finder(handler);</div><div class="line"> std::vector<hueplusplus::BridgeFinder::BridgeIdentification> bridges = finder.findBridges();</div><div class="line"> <span class="keywordflow">if</span> (bridges.empty())</div><div class="line"> {</div><div class="line"> std::cerr << <span class="stringliteral">"No bridges found\n"</span>;</div><div class="line"> <span class="keywordflow">return</span>;</div><div class="line"> }</div></div><!-- fragment --><p> At this point you may want to decide whether to use a <a class="el" href="shared-state.html">shared state</a> cache model or keep the default settings.</p>
<p>If you have found the Bridge you were looking for, you can then move on with the authentication process. To get a new username from the Bridge (for now) you simply call <a class="el" href="classhueplusplus_1_1_bridge_finder.html#a9ff121c380ceaceaf5da2b7a772e5c4b">getBridge(bridges[<index>])</a>, where index is your preferred Bridge from the part <a href="#searchingBridges">Searching for Bridges</a>. This requires the user to press the link button. </p><div class="fragment"><div class="line"> <a class="code" href="classhueplusplus_1_1_bridge.html">hueplusplus::Bridge</a> bridge = finder.getBridge(bridges[0]);</div></div><!-- fragment --><p> If you on the other hand already have a username you can add your bridge like so </p><div class="fragment"><div class="line"> finder.addUsername(bridges[0].mac, <span class="stringliteral">"<username>"</span>);</div><div class="line"> <a class="code" href="classhueplusplus_1_1_bridge.html">hueplusplus::Bridge</a> bridge = finder.getBridge(bridges[0]);</div></div><!-- fragment --><p> If you do not want to use the BridgeFinder or you already know the ip and username of your bridge you have the option to create your own Bridge object. Here you will need to provide the ip address, the port number, a username and an HttpHandler </p><div class="fragment"><div class="line"> <span class="comment">// For windows use std::make_shared<hueplusplus::WinHttpHandler>();</span></div><div class="line"> <span class="keyword">auto</span> handler = std::make_shared<hueplusplus::LinHttpHandler>();</div><div class="line"> <a class="code" href="classhueplusplus_1_1_bridge.html">hueplusplus::Bridge</a> bridge(<span class="stringliteral">"192.168.2.102"</span>, 80, <span class="stringliteral">"<username>"</span>, handler);</div></div><!-- fragment --><p>If you have your Bridge all set up, you can now control its lights. For that create a new Light object and call <a class="el" href="classhueplusplus_1_1_resource_list.html#a7bcf2ed48e70e9f11a4b6bdc24e0e611">lights().get(<id>)</a> on your bridge object to get a reference to a specific light, where id is the id of the light set internally by the Hue Bridge. </p><div class="fragment"><div class="line"> <a class="code" href="classhueplusplus_1_1_light.html">hueplusplus::Light</a> light1 = bridge.<a class="code" href="classhueplusplus_1_1_bridge.html#a7bd607246130312915a3b07116c72301">lights</a>().<a class="code" href="classhueplusplus_1_1_resource_list.html#a7bcf2ed48e70e9f11a4b6bdc24e0e611">get</a>(1);</div></div><!-- fragment --><p> If you don't know the id of a specific light or want to get an overview over all lights that are controlled by your bridge, you can get a vector containing them by calling <a class="el" href="classhueplusplus_1_1_resource_list.html#ad7b3bef47b0c09764377cbad327545df">getAll()</a> on your bridge object. If no lights are found the vector will be empty. </p><div class="fragment"><div class="line"> std::vector<hueplusplus::Light> lights = bridge.<a class="code" href="classhueplusplus_1_1_bridge.html#a7bd607246130312915a3b07116c72301">lights</a>().<a class="code" href="classhueplusplus_1_1_resource_list.html#ad7b3bef47b0c09764377cbad327545df">getAll</a>();</div></div><!-- fragment --><p> If you now want to control a light, call a specific function of it. </p><div class="fragment"><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#aab9db2db84ad55e19d7b46c77807973d">on</a>();</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#a103f8c3ab0a6bbf17839a9fd59049ce1">setBrightness</a>(120);</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#a4a32fef56140dccb003516842fe958f8">alertHueSaturation</a>({25500, 254});</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#ace958475e37b6273da1a47395076156d">setColorLoop</a>(<span class="keyword">true</span>);</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#a45c57a522e5785729fa7f557bf8591e3">setColorRGB</a>({255, 128, 0});</div><div class="line"> lights[1].off();</div><div class="line"> lights.at(1).setColorHue(4562);</div></div><!-- fragment --><p> But keep in mind that some light types do not have all functions available. So you might call a specific function, but nothing will happen. For that you might want to check what type of a light you are controlling. For that you can call the function <a class="el" href="classhueplusplus_1_1_light.html#abfff60ed1b992b11ebff8af37586e2a8">getColorType()</a>, which will return a ColorType. </p><div class="fragment"><div class="line"> <a class="code" href="namespacehueplusplus.html#aa4ee261126f0bc8edc07e67bc811dc43">hueplusplus::ColorType</a> type1 = light1.<a class="code" href="classhueplusplus_1_1_light.html#abfff60ed1b992b11ebff8af37586e2a8">getColorType</a>();</div></div><!-- fragment --><p> There's also a new way to check whether specific functions of a light are available: </p><div class="fragment"><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#af680548b576b57a713018a353d8c8a88">hasBrightnessControl</a>();</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#a4b013d5e1cff6bdc02f273d57fc0db22">hasTemperatureControl</a>();</div><div class="line"> light1.<a class="code" href="classhueplusplus_1_1_light.html#a661e357c5648ff574634a12b40680a6f">hasColorControl</a>();</div></div><!-- fragment --><p> These will either return true(light has specified function) or false(light lacks specified function).</p>
<p><a class="el" href="build.html">Build and install guide</a></p>
<p>If you want to build the library you can use cmake (at least version 3.8). First create a build folder and then execute cmake. </p><div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake ..</div></div><!-- fragment --><p> Then compile the code with make. If you are inpatient use the option -j<number>, where number specifies how many files are compiled at the same time. Note this number should not exceed the number of cores*2 of your machine. </p><div class="fragment"><div class="line">make</div></div><!-- fragment --> <div class="fragment"><div class="line">make -j4</div></div><!-- fragment --><p> If you want to install the library use </p><div class="fragment"><div class="line">make install</div></div><!-- fragment --><p> To remove it </p><div class="fragment"><div class="line">make uninstall</div></div><!-- fragment --><p>If you have a project that already uses CMake you probably want to add the hueplusplus library directly in your cmake file. For that the best way is to use find_package(). When cmake finds the hueplusplus library you can then link against either the shared or static version of the library. </p><div class="fragment"><div class="line">find_package(hueplusplus REQUIRED)</div><div class="line"></div><div class="line">target_link_libraries(<executable> PUBLIC hueplusplusstatic)</div></div><!-- fragment --><p> But this will only work if the hueplusplus library is already installed. To get around this problem there is a pretty awesome way. If you have the hueplusplus repository included in your project repository (as a submodule) or know where the folder lives you can do the following: </p><div class="fragment"><div class="line">find_package(hueplusplus QUIET)</div><div class="line">if(NOT hueplusplus_FOUND)</div><div class="line"> message(STATUS "-- hueplusplus not found, building it")</div><div class="line"> add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/<path to directory>/hueplusplus" "${CMAKE_CURRENT_BINARY_DIR}/hueplusplus")</div><div class="line">endif()</div><div class="line"></div><div class="line">target_link_libraries(<executable> PUBLIC hueplusplusstatic)</div></div><!-- fragment --><p> This will check if the hueplusplus library was found by find_package() and if not it will use the specified path to the library source and compile it during the build process.</p>
<p>If you additionally want to run the tests use cmake with the option -Dhueplusplus_TESTS=ON. Testing is done with Google gtest and gmock. Note that you wont need to install gtest/gmock yourself, because cmake will automatically download them and include them during the build. Since I added a custom target you will only need to call "make unittest" and the tests are compiled and executed. </p><div class="fragment"><div class="line">mkdir build</div><div class="line">cd build</div><div class="line">cmake .. -Dhueplusplus_TESTS=ON</div><div class="line">make unittest</div></div><!-- fragment --><p> If you also want to execute coverage tests you will need to install gcov and lcov yourself. To run the coverage test use </p><div class="fragment"><div class="line">make coveragetest</div></div><!-- fragment --><ul>
<li><a class="el" href="getting-started.html">Getting started</a></li>
<li><a class="el" href="build.html">Build and install</a></li>
<li><a class="el" href="shared-state.html">Shared state cache</a></li>
<li><a class="el" href="transactions.html">Transactions</a></li>
<li><a class="el" href="sensors.html">Sensors</a> </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>