python-amazon-echo 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- amazon_echo/__init__.py +5 -1
- amazon_echo/client.py +540 -89
- amazon_echo/const.py +74 -1
- amazon_echo/endpoints.py +191 -0
- amazon_echo/models.py +43 -0
- {python_amazon_echo-0.1.1.dist-info → python_amazon_echo-0.3.0.dist-info}/METADATA +72 -6
- python_amazon_echo-0.3.0.dist-info/RECORD +16 -0
- python_amazon_echo-0.1.1.dist-info/RECORD +0 -15
- {python_amazon_echo-0.1.1.dist-info → python_amazon_echo-0.3.0.dist-info}/WHEEL +0 -0
- {python_amazon_echo-0.1.1.dist-info → python_amazon_echo-0.3.0.dist-info}/entry_points.txt +0 -0
- {python_amazon_echo-0.1.1.dist-info → python_amazon_echo-0.3.0.dist-info}/licenses/LICENSE +0 -0
amazon_echo/const.py
CHANGED
|
@@ -4,7 +4,7 @@ from __future__ import annotations
|
|
|
4
4
|
|
|
5
5
|
from typing import Any, Final
|
|
6
6
|
|
|
7
|
-
VERSION: Final = "0.
|
|
7
|
+
VERSION: Final = "0.3.0"
|
|
8
8
|
|
|
9
9
|
# Identity of the Alexa iOS app, which is what a registration impersonates.
|
|
10
10
|
APP_NAME: Final = "Amazon Echo for Home Assistant"
|
|
@@ -28,6 +28,8 @@ AUTH_HOST: Final = "api.amazon.com"
|
|
|
28
28
|
AVS_HOST: Final = "api.amazonalexa.com"
|
|
29
29
|
PUSH_HOST: Final = "bob-dispatch-prod-{region}.amazon.com"
|
|
30
30
|
PUSH_VERSION: Final = "v20160207"
|
|
31
|
+
# Communications service; every marketplace has an alias of the same host.
|
|
32
|
+
COMMS_HOST: Final = "alexa-comms-mobile-service.{domain}"
|
|
31
33
|
|
|
32
34
|
# Retail domains whose accounts live outside the EU push region.
|
|
33
35
|
REGION_BY_DOMAIN: Final[dict[str, str]] = {
|
|
@@ -65,6 +67,48 @@ MEDIA_COMMANDS: Final[dict[str, str]] = {
|
|
|
65
67
|
"repeat": "RepeatCommand",
|
|
66
68
|
}
|
|
67
69
|
|
|
70
|
+
# "Tell me…" routines actions: name → behavior node type.
|
|
71
|
+
INFO_SKILLS: Final[dict[str, str]] = {
|
|
72
|
+
"calendar_today": "Alexa.Calendar.PlayToday",
|
|
73
|
+
"calendar_tomorrow": "Alexa.Calendar.PlayTomorrow",
|
|
74
|
+
"calendar_next": "Alexa.Calendar.PlayNext",
|
|
75
|
+
"date": "Alexa.Date.Play",
|
|
76
|
+
"time": "Alexa.Time.Play",
|
|
77
|
+
"national_news": "Alexa.News.NationalNews",
|
|
78
|
+
"flash_briefing": "Alexa.FlashBriefing.Play",
|
|
79
|
+
"traffic": "Alexa.Traffic.Play",
|
|
80
|
+
"weather": "Alexa.Weather.Play",
|
|
81
|
+
"clean_up": "Alexa.CleanUp.Play",
|
|
82
|
+
"good_morning": "Alexa.GoodMorning.Play",
|
|
83
|
+
"sing_a_song": "Alexa.SingASong.Play",
|
|
84
|
+
"fun_fact": "Alexa.FunFact.Play",
|
|
85
|
+
"joke": "Alexa.Joke.Play",
|
|
86
|
+
"tell_story": "Alexa.TellStory.Play",
|
|
87
|
+
"im_home": "Alexa.ImHome.Play",
|
|
88
|
+
"good_night": "Alexa.GoodNight.Play",
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
DROP_IN_MODES: Final[dict[str, str]] = {"all": "All", "home": "Home", "off": "Off"}
|
|
92
|
+
|
|
93
|
+
# GraphQL feature instances with a fixed meaning.
|
|
94
|
+
AMBIENT_MODE_INSTANCE: Final = "FTV.AmbientMode"
|
|
95
|
+
REMOTE_BATTERY_INSTANCE: Final = "Remote.Battery"
|
|
96
|
+
# The Amazon Air Quality Monitor reports its readings as numbered ranges.
|
|
97
|
+
AQM_DEVICE_TYPE: Final = "AEZME1X38KDRA"
|
|
98
|
+
AQM_LED_INSTANCE: Final = "11"
|
|
99
|
+
AQM_RANGES: Final[dict[str, str]] = {
|
|
100
|
+
"4": "humidity",
|
|
101
|
+
"5": "voc",
|
|
102
|
+
"6": "pm25",
|
|
103
|
+
"7": "pm10",
|
|
104
|
+
"8": "co",
|
|
105
|
+
"9": "air_quality",
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
GUARD_MODEL: Final = "REDROCK_GUARD_PANEL"
|
|
109
|
+
GUARD_SKILL_ID: Final = "amzn1.ask.skill.f71a9b50-e99a-4669-a226-d50ebb5e0830"
|
|
110
|
+
GUARD_CAPABILITY: Final = "GUARD_EARCON"
|
|
111
|
+
|
|
68
112
|
# What the Alexa app declares to AVS (PUT /v1/devices/@self/capabilities).
|
|
69
113
|
# Without `Alexa.Mobile.Push` the HTTP/2 channel stays silent.
|
|
70
114
|
_LEGACY_FLAGS: Final[dict[str, Any]] = {
|
|
@@ -223,6 +267,7 @@ query echoEndpoints {
|
|
|
223
267
|
endpoints {
|
|
224
268
|
endpointId: id
|
|
225
269
|
friendlyNameObject { value { text } }
|
|
270
|
+
manufacturer { value { text } }
|
|
226
271
|
model { value { text } }
|
|
227
272
|
displayCategories { primary { value } }
|
|
228
273
|
dmsIdentifier { deviceType dsn }
|
|
@@ -231,6 +276,7 @@ query echoEndpoints {
|
|
|
231
276
|
features {
|
|
232
277
|
name
|
|
233
278
|
instance
|
|
279
|
+
operations { name }
|
|
234
280
|
properties {
|
|
235
281
|
name
|
|
236
282
|
type
|
|
@@ -241,6 +287,24 @@ query echoEndpoints {
|
|
|
241
287
|
... on ToggleState { toggleStateValue }
|
|
242
288
|
... on Volume { vol: value { value } }
|
|
243
289
|
... on Reachability { reachabilityStatusValue }
|
|
290
|
+
... on Illuminance { illuminanceValue { value } }
|
|
291
|
+
... on DetectionState { detectionStateValue }
|
|
292
|
+
... on RelativeHumidity { relativeHumidityValue { value } }
|
|
293
|
+
... on RangeValue { rangeValue { value } }
|
|
294
|
+
... on Power { powerStateValue }
|
|
295
|
+
... on Brightness { brightnessStateValue }
|
|
296
|
+
... on Color { colorStateValue { hue saturation brightness } }
|
|
297
|
+
... on ColorTemperature { colorTemperatureInKelvinStateValue }
|
|
298
|
+
... on Lock { lockState }
|
|
299
|
+
... on Mode { modeValue { value } }
|
|
300
|
+
}
|
|
301
|
+
configuration {
|
|
302
|
+
... on ModeConfiguration {
|
|
303
|
+
modeOptions {
|
|
304
|
+
value
|
|
305
|
+
modeResources { friendlyName { value { text } } }
|
|
306
|
+
}
|
|
307
|
+
}
|
|
244
308
|
}
|
|
245
309
|
}
|
|
246
310
|
}
|
|
@@ -248,6 +312,15 @@ query echoEndpoints {
|
|
|
248
312
|
}
|
|
249
313
|
"""
|
|
250
314
|
|
|
315
|
+
# The Alexa Guard panel only shows up in the legacy appliance list.
|
|
316
|
+
QUERY_APPLIANCES: Final = """
|
|
317
|
+
query echoAppliances {
|
|
318
|
+
endpoints(endpointsQueryParams: {paginationParams: {disablePagination: true}}) {
|
|
319
|
+
items { legacyAppliance { applianceId modelName entityId } }
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
"""
|
|
323
|
+
|
|
251
324
|
MUTATION_SET_ENDPOINT_FEATURES: Final = """
|
|
252
325
|
mutation setEndpointFeatures($input: SetEndpointFeaturesInput!) {
|
|
253
326
|
setEndpointFeatures(setEndpointFeaturesInput: $input) {
|
amazon_echo/endpoints.py
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
"""Parsers for the GraphQL endpoints (Alexa devices and smart-home devices).
|
|
2
|
+
|
|
3
|
+
A GraphQL endpoint lists *features* (``power``, ``temperatureSensor``…), each
|
|
4
|
+
with typed *properties*. They are flattened here into plain values, keyed by
|
|
5
|
+
what the property carries rather than by device model, so any device that
|
|
6
|
+
reports a property gets its value. The same shape arrives over push
|
|
7
|
+
(``EventBus:AlexaMobile::FDAL``), without the query aliases.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from collections.abc import Iterator
|
|
13
|
+
import re
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from .const import (
|
|
17
|
+
AMBIENT_MODE_INSTANCE,
|
|
18
|
+
AQM_DEVICE_TYPE,
|
|
19
|
+
AQM_LED_INSTANCE,
|
|
20
|
+
AQM_RANGES,
|
|
21
|
+
REMOTE_BATTERY_INSTANCE,
|
|
22
|
+
)
|
|
23
|
+
from .models import Endpoint
|
|
24
|
+
|
|
25
|
+
# What Amazon reports while a temperature sensor calibrates (after a reboot).
|
|
26
|
+
_CALIBRATING = -280
|
|
27
|
+
_DETECTION = {"motionSensor": "motion", "contactSensor": "contact"}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def format_mac(value: str | None) -> str | None:
|
|
31
|
+
"""Return ``aa:bb:cc:dd:ee:ff`` for any 12-hex-digit MAC spelling."""
|
|
32
|
+
digits = re.sub(r"[^0-9a-fA-F]", "", value or "").lower()
|
|
33
|
+
if len(digits) != 12:
|
|
34
|
+
return None
|
|
35
|
+
return ":".join(digits[i : i + 2] for i in range(0, 12, 2))
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def dig(data: Any, *path: str) -> Any:
|
|
39
|
+
"""Walk nested dicts, returning None as soon as a level is missing."""
|
|
40
|
+
for key in path:
|
|
41
|
+
if not isinstance(data, dict):
|
|
42
|
+
return None
|
|
43
|
+
data = data.get(key)
|
|
44
|
+
return data
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _celsius(reading: Any) -> float | None:
|
|
48
|
+
value = dig(reading, "value")
|
|
49
|
+
if not isinstance(value, (int, float)) or value == _CALIBRATING:
|
|
50
|
+
return None
|
|
51
|
+
if dig(reading, "scale") == "FAHRENHEIT":
|
|
52
|
+
return round((value - 32) / 1.8, 1)
|
|
53
|
+
return value
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _switched(value: Any) -> bool | None:
|
|
57
|
+
return None if value is None else value == "ON"
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _values(
|
|
61
|
+
feature: str, instance: str | None, prop: dict[str, Any], device_type: str | None
|
|
62
|
+
) -> Iterator[tuple[str, Any]]:
|
|
63
|
+
"""Yield the (key, value) pairs one property stands for."""
|
|
64
|
+
name = prop.get("name")
|
|
65
|
+
if name == "temperature":
|
|
66
|
+
# `temp` is the query alias, `value` what a push update carries
|
|
67
|
+
yield "temperature", _celsius(prop.get("temp") or prop.get("value"))
|
|
68
|
+
elif name == "volume":
|
|
69
|
+
yield "volume", dig(prop.get("vol") or prop.get("value"), "value")
|
|
70
|
+
elif "reachabilityStatusValue" in prop:
|
|
71
|
+
status = prop["reachabilityStatusValue"]
|
|
72
|
+
yield "reachable", None if status is None else status == "OK"
|
|
73
|
+
elif "illuminanceValue" in prop:
|
|
74
|
+
yield "illuminance", dig(prop, "illuminanceValue", "value")
|
|
75
|
+
elif "detectionStateValue" in prop and feature in _DETECTION:
|
|
76
|
+
state = prop["detectionStateValue"]
|
|
77
|
+
yield _DETECTION[feature], None if state is None else state == "DETECTED"
|
|
78
|
+
elif "relativeHumidityValue" in prop:
|
|
79
|
+
yield "humidity", dig(prop, "relativeHumidityValue", "value")
|
|
80
|
+
elif "rangeValue" in prop:
|
|
81
|
+
if device_type == AQM_DEVICE_TYPE and instance in AQM_RANGES:
|
|
82
|
+
yield AQM_RANGES[instance], dig(prop, "rangeValue", "value")
|
|
83
|
+
elif "powerStateValue" in prop:
|
|
84
|
+
yield "power", _switched(prop["powerStateValue"])
|
|
85
|
+
elif "brightnessStateValue" in prop:
|
|
86
|
+
yield "brightness", prop["brightnessStateValue"]
|
|
87
|
+
elif "colorStateValue" in prop:
|
|
88
|
+
yield "color", prop["colorStateValue"]
|
|
89
|
+
elif "colorTemperatureInKelvinStateValue" in prop:
|
|
90
|
+
yield "color_temperature", prop["colorTemperatureInKelvinStateValue"]
|
|
91
|
+
elif "lockState" in prop:
|
|
92
|
+
yield "lock", prop["lockState"]
|
|
93
|
+
elif "modeValue" in prop:
|
|
94
|
+
yield "mode", dig(prop, "modeValue", "value")
|
|
95
|
+
elif "toggleStateValue" in prop:
|
|
96
|
+
value = _switched(prop["toggleStateValue"])
|
|
97
|
+
if instance == AMBIENT_MODE_INSTANCE:
|
|
98
|
+
yield "ambient_mode", value
|
|
99
|
+
elif device_type == AQM_DEVICE_TYPE and instance == AQM_LED_INSTANCE:
|
|
100
|
+
yield "aqm_led", value
|
|
101
|
+
elif "batteryValue" in prop:
|
|
102
|
+
yield "battery", dig(prop, "batteryValue", "levelPercentage")
|
|
103
|
+
elif "inventoryLevelValue" in prop:
|
|
104
|
+
level = dig(prop, "inventoryLevelValue", "value")
|
|
105
|
+
if instance == REMOTE_BATTERY_INSTANCE:
|
|
106
|
+
yield "remote_battery", level
|
|
107
|
+
elif "battery" in (instance or "").casefold():
|
|
108
|
+
yield "battery", level
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
def parse_features(
|
|
112
|
+
features: list[dict[str, Any]] | None, *, device_type: str | None = None
|
|
113
|
+
) -> dict[str, Any]:
|
|
114
|
+
"""Flatten GraphQL features into values.
|
|
115
|
+
|
|
116
|
+
A key is present when the endpoint has the feature; its value is None
|
|
117
|
+
while Amazon cannot read it (device unreachable, sensor calibrating).
|
|
118
|
+
|
|
119
|
+
Keys: ``reachable``, ``temperature`` (°C), ``humidity`` (%),
|
|
120
|
+
``illuminance`` (lx), ``motion``, ``contact`` (True = open), ``battery``
|
|
121
|
+
(%), ``remote_battery`` (%), ``volume``, ``ambient_mode``, ``power``,
|
|
122
|
+
``brightness`` (0-100), ``color`` (``hue`` 0-360, ``saturation`` and
|
|
123
|
+
``brightness`` 0-1), ``color_temperature`` (K), ``lock`` (``LOCKED`` /
|
|
124
|
+
``UNLOCKED`` / ``JAMMED``), ``mode`` with ``mode_instance`` and
|
|
125
|
+
``mode_options`` (name → value) and, for the Amazon Air Quality Monitor,
|
|
126
|
+
``pm25`` / ``pm10`` (µg/m³), ``voc`` (index), ``co`` (ppm),
|
|
127
|
+
``air_quality`` (index) and ``aqm_led``.
|
|
128
|
+
"""
|
|
129
|
+
state: dict[str, Any] = {}
|
|
130
|
+
for feature in features or []:
|
|
131
|
+
name, instance = feature.get("name") or "", feature.get("instance")
|
|
132
|
+
for prop in feature.get("properties") or []:
|
|
133
|
+
for key, value in _values(name, instance, prop or {}, device_type):
|
|
134
|
+
# two features can carry a battery: keep the one that reads
|
|
135
|
+
if value is not None or state.get(key) is None:
|
|
136
|
+
state[key] = value
|
|
137
|
+
options = dig(feature, "configuration", "modeOptions")
|
|
138
|
+
if name == "mode" and options:
|
|
139
|
+
state["mode_instance"] = instance
|
|
140
|
+
state["mode_options"] = {
|
|
141
|
+
dig(option, "modeResources", "friendlyName", "value", "text")
|
|
142
|
+
or option["value"]: option["value"]
|
|
143
|
+
for option in options
|
|
144
|
+
if option.get("value")
|
|
145
|
+
}
|
|
146
|
+
return state
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def parse_endpoint(endpoint: dict[str, Any]) -> dict[str, Any]:
|
|
150
|
+
"""Flatten one GraphQL endpoint of an Alexa device (see ``parse_features``)."""
|
|
151
|
+
mac = None
|
|
152
|
+
for connection in endpoint.get("connections") or []:
|
|
153
|
+
if connection.get("type") == "TCP_IP" and connection.get("macAddress"):
|
|
154
|
+
mac = format_mac(connection["macAddress"])
|
|
155
|
+
return {
|
|
156
|
+
"endpoint_id": endpoint.get("endpointId"),
|
|
157
|
+
"model": dig(endpoint, "model", "value", "text"),
|
|
158
|
+
"mac": mac,
|
|
159
|
+
"temperature": None,
|
|
160
|
+
"volume": None,
|
|
161
|
+
"reachable": None,
|
|
162
|
+
"remote_battery": None,
|
|
163
|
+
"ambient_mode": None,
|
|
164
|
+
"dnd": dig(endpoint, "settings", "doNotDisturb", "toggleValue"),
|
|
165
|
+
**parse_features(
|
|
166
|
+
endpoint.get("features"),
|
|
167
|
+
device_type=dig(endpoint, "dmsIdentifier", "deviceType"),
|
|
168
|
+
),
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def build_endpoint(endpoint: dict[str, Any]) -> Endpoint:
|
|
173
|
+
"""Build an :class:`Endpoint` from one GraphQL endpoint."""
|
|
174
|
+
features = endpoint.get("features") or []
|
|
175
|
+
device_type = dig(endpoint, "dmsIdentifier", "deviceType")
|
|
176
|
+
return Endpoint(
|
|
177
|
+
id=endpoint["endpointId"],
|
|
178
|
+
name=dig(endpoint, "friendlyNameObject", "value", "text")
|
|
179
|
+
or endpoint["endpointId"],
|
|
180
|
+
category=dig(endpoint, "displayCategories", "primary", "value") or "OTHER",
|
|
181
|
+
manufacturer=dig(endpoint, "manufacturer", "value", "text"),
|
|
182
|
+
model=dig(endpoint, "model", "value", "text"),
|
|
183
|
+
serial=dig(endpoint, "dmsIdentifier", "dsn"),
|
|
184
|
+
device_type=device_type,
|
|
185
|
+
operations=frozenset(
|
|
186
|
+
f"{feature.get('name')}.{operation.get('name')}"
|
|
187
|
+
for feature in features
|
|
188
|
+
for operation in feature.get("operations") or []
|
|
189
|
+
),
|
|
190
|
+
state=parse_features(features, device_type=device_type),
|
|
191
|
+
)
|
amazon_echo/models.py
CHANGED
|
@@ -152,6 +152,7 @@ class VoiceRecord:
|
|
|
152
152
|
response: str | None = None
|
|
153
153
|
intent: str | None = None
|
|
154
154
|
person: str | None = None
|
|
155
|
+
person_type: str | None = None
|
|
155
156
|
|
|
156
157
|
|
|
157
158
|
@dataclass(slots=True, kw_only=True)
|
|
@@ -163,3 +164,45 @@ class AuxPort:
|
|
|
163
164
|
plugged: bool = False
|
|
164
165
|
enabled: bool = False
|
|
165
166
|
active: bool = False
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
@dataclass(slots=True, kw_only=True)
|
|
170
|
+
class Endpoint:
|
|
171
|
+
"""A smart-home device linked to the account (lamp, plug, sensor, lock…).
|
|
172
|
+
|
|
173
|
+
``state`` holds the values of ``parse_features``; ``operations`` the
|
|
174
|
+
``feature.operation`` pairs the endpoint accepts (``power.turnOn``).
|
|
175
|
+
"""
|
|
176
|
+
|
|
177
|
+
id: str
|
|
178
|
+
name: str
|
|
179
|
+
category: str
|
|
180
|
+
manufacturer: str | None = None
|
|
181
|
+
model: str | None = None
|
|
182
|
+
serial: str | None = None
|
|
183
|
+
device_type: str | None = None
|
|
184
|
+
operations: frozenset[str] = frozenset()
|
|
185
|
+
state: dict[str, Any] = field(default_factory=dict)
|
|
186
|
+
|
|
187
|
+
@property
|
|
188
|
+
def is_amazon_device(self) -> bool:
|
|
189
|
+
"""Return True for Amazon hardware (Echo Glow, Air Quality Monitor)."""
|
|
190
|
+
return self.serial is not None
|
|
191
|
+
|
|
192
|
+
def supports(self, feature: str, operation: str) -> bool:
|
|
193
|
+
"""Return True when the endpoint accepts ``operation`` of ``feature``."""
|
|
194
|
+
return f"{feature}.{operation}" in self.operations
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
@dataclass(slots=True, kw_only=True)
|
|
198
|
+
class Guard:
|
|
199
|
+
"""The Alexa Guard panel of the account."""
|
|
200
|
+
|
|
201
|
+
entity_id: str
|
|
202
|
+
appliance_id: str
|
|
203
|
+
state: str | None = None
|
|
204
|
+
|
|
205
|
+
@property
|
|
206
|
+
def armed(self) -> bool:
|
|
207
|
+
"""Return True while Guard is in away mode."""
|
|
208
|
+
return self.state == "ARMED_AWAY"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: python-amazon-echo
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
4
4
|
Summary: Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery
|
|
5
5
|
Project-URL: Homepage, https://github.com/hudsonbrendon/python-amazon-echo
|
|
6
6
|
Project-URL: Repository, https://github.com/hudsonbrendon/python-amazon-echo
|
|
@@ -52,9 +52,22 @@ on the local network. It is not affiliated with Amazon.
|
|
|
52
52
|
volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
|
|
53
53
|
mode, adaptive volume and any per-device setting key (speaking rate, time zone,
|
|
54
54
|
captions, …).
|
|
55
|
-
- **Actions.** Volume, stop, speak, announce,
|
|
56
|
-
skills, routines,
|
|
57
|
-
|
|
55
|
+
- **Actions.** Volume, stop, speak, announce (spoken, shown or both), text
|
|
56
|
+
command, sounds, music, skills, routines, the "tell me…" info skills (weather,
|
|
57
|
+
traffic, flash briefing, a joke…), any other behavior node type, transport
|
|
58
|
+
commands, Bluetooth, reboot, Echo Show background image.
|
|
59
|
+
- **Notifications to the Alexa app.** A mobile push, or one that opens Drop In.
|
|
60
|
+
- **Communication preferences.** Calls and messages, announcements and Drop In
|
|
61
|
+
per device.
|
|
62
|
+
- **Amazon Kids.** The child profiles of the household, which one a device is
|
|
63
|
+
assigned to, and switching a device into or out of Kids mode.
|
|
64
|
+
- **Alarms, timers and reminders.** List all, create, delete; switch an alarm
|
|
65
|
+
on or off and skip its next ring.
|
|
66
|
+
- **Smart home.** Every device linked to the account (lamps, plugs, sensors,
|
|
67
|
+
locks, Echo Glow, the Air Quality Monitor) with its state and the operations
|
|
68
|
+
it accepts; sensors of the Echos themselves (illuminance, motion, humidity);
|
|
69
|
+
state changes pushed by Amazon decoded into the same values.
|
|
70
|
+
- **Alexa Guard.** Read the panel, arm (away) and disarm (home).
|
|
58
71
|
- **Lists.** Shopping, to-do and custom lists with full item CRUD.
|
|
59
72
|
- **Voice history.**
|
|
60
73
|
- **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
|
|
@@ -121,6 +134,26 @@ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 6
|
|
|
121
134
|
await push.stop()
|
|
122
135
|
```
|
|
123
136
|
|
|
137
|
+
Smart home:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
for endpoint in await client.get_smart_home_endpoints():
|
|
141
|
+
print(endpoint.name, endpoint.category, endpoint.state)
|
|
142
|
+
|
|
143
|
+
lamp = next(e for e in await client.get_smart_home_endpoints() if e.category == "LIGHT")
|
|
144
|
+
if lamp.supports("brightness", "setBrightness"):
|
|
145
|
+
await client.call_feature(
|
|
146
|
+
lamp.id, "brightness", "setBrightness", payload={"brightness": 40}
|
|
147
|
+
)
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`endpoint.state` uses the keys documented in
|
|
151
|
+
`amazon_echo.endpoints.parse_features` (`power`, `brightness`, `color`,
|
|
152
|
+
`color_temperature`, `temperature`, `humidity`, `battery`, `contact`, `motion`,
|
|
153
|
+
`lock`…); a key is there when the device has the feature, and is None while
|
|
154
|
+
Amazon cannot read it. `get_endpoint_states()` and `get_smart_home_endpoints()`
|
|
155
|
+
share one request when called within 5 seconds.
|
|
156
|
+
|
|
124
157
|
LAN:
|
|
125
158
|
|
|
126
159
|
```python
|
|
@@ -184,8 +217,9 @@ Credentials are read from `~/.config/amazon-echo/credentials.json`
|
|
|
184
217
|
|
|
185
218
|
## Verification
|
|
186
219
|
|
|
187
|
-
How each part was checked against a real amazon.com.br account on 2026-11-15
|
|
188
|
-
|
|
220
|
+
How each part was checked against a real amazon.com.br account on 2026-11-15
|
|
221
|
+
(the 0.2.0 additions on 2026-11-16). Everything is also covered by unit tests
|
|
222
|
+
with mocked HTTP.
|
|
189
223
|
|
|
190
224
|
- **live read** — called against Amazon through this library, answer parsed.
|
|
191
225
|
- **no-op write** — the value just read was written back to one Echo Plus and
|
|
@@ -210,6 +244,8 @@ HTTP.
|
|
|
210
244
|
| `set_volume` (sequence pipeline) | no-op write |
|
|
211
245
|
| `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
|
|
212
246
|
| `create_alarm` | ported |
|
|
247
|
+
| `create_alarm(music=…)` (music alarm that reuses the station of an existing one) | ported from Alexa Media Player's request, never sent |
|
|
248
|
+
| `play_music(timer=…)` (stop after that many seconds) | ported from Alexa Media Player's payload, never sent |
|
|
213
249
|
| `create_timer` | ported — body inferred from field names in the app, never sent |
|
|
214
250
|
| `set_wake_word` | ported |
|
|
215
251
|
| `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
|
|
@@ -218,6 +254,19 @@ HTTP.
|
|
|
218
254
|
| `add_list_item`, `update_list_item`, `delete_list_item` | ported |
|
|
219
255
|
| `get_voice_history` | live read |
|
|
220
256
|
| `call_feature` | ported |
|
|
257
|
+
| `get_endpoint_states` with the 0.2.0 query (illuminance, motion, humidity, air quality) | live read: a few hundred endpoints, no GraphQL error. Four devices advertise a light sensor and report no value; no device of the account reports motion, humidity or air quality, so those are unit tested only |
|
|
258
|
+
| `get_smart_home_endpoints` | live read; power, brightness, colour, colour temperature, temperature, battery, contact, motion and lock states and the operation names all parsed |
|
|
259
|
+
| `parse_endpoint_update` (smart-home push) | ported, not replayed live — no push stream on the test session |
|
|
260
|
+
| Smart-home operations through `call_feature` (`turnOn`, `turnOff`, `setBrightness`, `setColor`, `setColorTemperature`, `setMode`, `lock`, `unlock`) | ported, not replayed live — they change a device's visible state. The request shapes of `power`, `brightness`, `lock` and `toggle` are the ones in the Alexa app; the payload of `setColorTemperature` is inferred |
|
|
261
|
+
| `get_communication_preferences` | verified live once (an Echo Plus answered `announcements: true, communications: true, drop_in: all`); otherwise the service answered HTTP 503 on about 95 % of 60+ spaced requests on 2026-11-16, on both the `.com` and the marketplace host, with cookies or a bearer token |
|
|
262
|
+
| `set_communications`, `set_announcements`, `set_drop_in` | ported, not replayed live — the no-op write was attempted three times each and the service answered 503 every time |
|
|
263
|
+
| `get_device_preferences`, `get_kids_mode`, `get_children`, `get_kids_profile` | live read |
|
|
264
|
+
| `set_kids_mode` | ported, not replayed live — it changes how a device behaves |
|
|
265
|
+
| `get_guard` | live for an account without Guard (the appliance list is read, no panel is found, None); the state read is ported — the test account has no Guard |
|
|
266
|
+
| `set_guard` | ported, not replayed live — Guard was not touched |
|
|
267
|
+
| `info_skill`, `send_sequence`, `send_mobile_push`, `send_drop_in_notification`, `announce(method=…)` | ported, not replayed live — audible, or visible on a phone |
|
|
268
|
+
| `enable_alarm`, `disable_alarm`, `skip_next_alarm` | ported, not replayed live |
|
|
269
|
+
| `set_background_image` | ported, not replayed live — it changes what an Echo Show displays |
|
|
221
270
|
| `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
|
|
222
271
|
| `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
|
|
223
272
|
|
|
@@ -242,6 +291,9 @@ HTTP.
|
|
|
242
291
|
pass a naive datetime in the Echo's local time if the host lives elsewhere.
|
|
243
292
|
- **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
|
|
244
293
|
and ignored.
|
|
294
|
+
- **Music alarms** can only reuse a station: `create_alarm(music=…)` takes a
|
|
295
|
+
music alarm that already exists on the account (create one in the Alexa app
|
|
296
|
+
first) and wakes with the same station. Amazon has no public search for one.
|
|
245
297
|
- **`create_timer` is unverified** (see the table). Use
|
|
246
298
|
`text_command(device, "set a timer for 5 minutes")` if it is rejected.
|
|
247
299
|
- **Voice history** comes 10 records per call; at most 50 are fetched.
|
|
@@ -250,6 +302,20 @@ HTTP.
|
|
|
250
302
|
sends `PUSH_NOTIFICATION_CHANGE`).
|
|
251
303
|
- `devices-v2` no longer reports MAC addresses or battery levels for most
|
|
252
304
|
devices; the MAC comes from GraphQL and is missing for apps and groups.
|
|
305
|
+
- **Communication preferences** come from a service that fails for some
|
|
306
|
+
accounts (HTTP 503 on the test account). The call is not retried and raises
|
|
307
|
+
`AmazonEchoRateLimitError`; treat it as "not available for this device".
|
|
308
|
+
- **Guard** is looked up once per client: an account that gets Guard later is
|
|
309
|
+
noticed by a new client. The free version of Guard was retired by Amazon in
|
|
310
|
+
most countries; the code follows `alexapy` and could not be run.
|
|
311
|
+
- **Smart-home state** is what Amazon last heard from the device's own cloud.
|
|
312
|
+
A value Amazon cannot read is None, and `reachable` is False for a device its
|
|
313
|
+
cloud reports offline.
|
|
314
|
+
- **Locks.** Amazon offers `unlock` only for some locks; check
|
|
315
|
+
`endpoint.supports("lock", "unlock")`.
|
|
316
|
+
- **Deleting voice history is not implemented.** The only endpoint the existing
|
|
317
|
+
clients use for it, `/api/activities`, answers 404 since Amazon moved the
|
|
318
|
+
history to the privacy hub.
|
|
253
319
|
- Amazon can change or remove any of this without notice.
|
|
254
320
|
|
|
255
321
|
## Development
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
amazon_echo/__init__.py,sha256=qY8C7gE4GVFBxuYAtrbgmhhoWxM8EAFej8HRcc2LuNo,1437
|
|
2
|
+
amazon_echo/__main__.py,sha256=1Hhd7w2cW5Z9jmwO1OThhcj6gbTLVqAQu5fAMqijJ_0,4325
|
|
3
|
+
amazon_echo/auth.py,sha256=O5SAtY5Wf76-LtFOkHJvrzlNoZdprgJsx5-3crEPUGQ,14417
|
|
4
|
+
amazon_echo/client.py,sha256=7AP2eBJ6_E_y029m8LwSEcz9d0WT0MR5Gu-YSrpuLdA,80593
|
|
5
|
+
amazon_echo/const.py,sha256=vOG2d3FC5ewenGSNrFwXi7-X0Vp4GrPejcVjp2YQWrg,11880
|
|
6
|
+
amazon_echo/endpoints.py,sha256=_6vXYWtwGIR_2IjVFJAXWP1vR6jwzIpZ4upkRctwBp8,7925
|
|
7
|
+
amazon_echo/exceptions.py,sha256=7ETH4C2sKbKEJWnJ30ygAO0a_GiD5PWmDHJCSVTedAU,1120
|
|
8
|
+
amazon_echo/local.py,sha256=KHwwgC2-MzFZ0wBaxXRuotyr7-zrrenzfM0P3BEMRvE,3080
|
|
9
|
+
amazon_echo/models.py,sha256=ZKEHuiyG7hqRt5M8nufyf1nyaRZ2-l1WXlOCzG4UH7A,5258
|
|
10
|
+
amazon_echo/push.py,sha256=KMcHeDLgRxEjCQpTybiJUAUNTFTxlDMpTVPDv0ZYAzE,11206
|
|
11
|
+
amazon_echo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
python_amazon_echo-0.3.0.dist-info/METADATA,sha256=TFFdzx2CS4r1ZfO3jl7f-LFyeSZ4dxZarv0LibnZbls,17589
|
|
13
|
+
python_amazon_echo-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
14
|
+
python_amazon_echo-0.3.0.dist-info/entry_points.txt,sha256=rbZJ8BI8kkiDTV9cKk6acbHuyAm2xNYfpDBXQNw8Yb8,58
|
|
15
|
+
python_amazon_echo-0.3.0.dist-info/licenses/LICENSE,sha256=4Zgd3fbLJqWSkwKA-hh1rNN6DC9tNQ3rWLX93fingOw,1071
|
|
16
|
+
python_amazon_echo-0.3.0.dist-info/RECORD,,
|
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
amazon_echo/__init__.py,sha256=lHodm3BV0aDFQsWu_TPBD8yaLiHEgwBMT8nEadkF2V0,1383
|
|
2
|
-
amazon_echo/__main__.py,sha256=1Hhd7w2cW5Z9jmwO1OThhcj6gbTLVqAQu5fAMqijJ_0,4325
|
|
3
|
-
amazon_echo/auth.py,sha256=O5SAtY5Wf76-LtFOkHJvrzlNoZdprgJsx5-3crEPUGQ,14417
|
|
4
|
-
amazon_echo/client.py,sha256=zCYu6AytIsa3-qYiNAphJP6C6opEhiwZbxlbkb1jLE8,62495
|
|
5
|
-
amazon_echo/const.py,sha256=7T_LijcR0DN8XVAGHDrMT4eOZw5YVNxv2NgU1wsGlyY,9128
|
|
6
|
-
amazon_echo/exceptions.py,sha256=7ETH4C2sKbKEJWnJ30ygAO0a_GiD5PWmDHJCSVTedAU,1120
|
|
7
|
-
amazon_echo/local.py,sha256=KHwwgC2-MzFZ0wBaxXRuotyr7-zrrenzfM0P3BEMRvE,3080
|
|
8
|
-
amazon_echo/models.py,sha256=2RV4rN4G2cNXAbIKDwEWxVgVdJxl98mlHjs6pmHWV6k,3967
|
|
9
|
-
amazon_echo/push.py,sha256=KMcHeDLgRxEjCQpTybiJUAUNTFTxlDMpTVPDv0ZYAzE,11206
|
|
10
|
-
amazon_echo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
-
python_amazon_echo-0.1.1.dist-info/METADATA,sha256=HPqX5Cc0tDe0H0OQ6mA0LmSdC5de2fnfxPCEuhpWvPQ,12236
|
|
12
|
-
python_amazon_echo-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
13
|
-
python_amazon_echo-0.1.1.dist-info/entry_points.txt,sha256=rbZJ8BI8kkiDTV9cKk6acbHuyAm2xNYfpDBXQNw8Yb8,58
|
|
14
|
-
python_amazon_echo-0.1.1.dist-info/licenses/LICENSE,sha256=4Zgd3fbLJqWSkwKA-hh1rNN6DC9tNQ3rWLX93fingOw,1071
|
|
15
|
-
python_amazon_echo-0.1.1.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|