Merge 4724a1fb25 into aad2e48098

micropython/umqtt.robust/README.rst

@@ -16,15 +16,15 @@ there's no power (mains outage or battery ran out). As you may imagine,
 umqtt.robust won't help you with your flat battery. Most computing
 systems are now networked, and communication is another weak link.
 This is especially true for wireless communications. If two of your
-systems can't connect reliably communicate via WiFi, umqtt.robust
+systems can't connect or reliably communicate over WiFi, umqtt.robust
 can't magically resolve that (but it may help with intermittent
 WiFi issues).
 
 What umqtt.robust tries to do is very simple - if while trying to
-perform some operation, it detects that connection to MQTT breaks,
+perform some operation, it detects that the connection to MQTT breaks,
-it tries to reconnect to it. That's good direction towards "robustness",
+it tries to reconnect. That's a good direction towards "robustness",
-but the problem that there is no single definition of what "robust"
+but the problem is that there no single definition of what "robust"
-is. Let's consider following usecase:
+is. Let's consider the following usecases:
 
 1. A temperature reading gets transmitted once a minute. Then the
 best option in case of a transmission error might be not doing
@@ -35,11 +35,11 @@ battery-powered, any connection retries will just drain battery and
 make device "less robust" (it will run out of juice sooner and more
 unexpectedly, which may be a criteria for "robustness").
 
-2. If there's a button, which communicates its press event, then
+2. If there's a button which communicates it's press event, then
-perhaps it's really worth to retry to deliver this event (a user
+perhaps it's really worth it to retry delivering this event (a user
 expects something to happen when they press the button, right?).
-But if a button is battery-power, unconstrained retries won't do
+But if a button is on battery-power, unconstrained retries still won't do
-much good still. Consider mains power outage for several hours,
+much good. Consider mains power outage for several hours,
 MQTT server down all this time, and battery-powered button trying
 to re-publish event every second. It will likely drain battery
 during this time, which is very non-robust. Perhaps, if a press
@@ -48,10 +48,10 @@ on what press does, the above may be good for a button turning
 on lights, but not for something else!)
 
 3. Finally, let's consider security sensors, like a window broken
-sensor. That's the hardest case. Apparently, those events are
+sensor. That's the hardest case. Those events are
 important enough to be delivered no matter what. But if done with
 short, dumb retries, it will only lead to quick battery drain. So,
-a robust device would retry, but in smart manner, to let battery
+a robust device would retry, but in a smart manner to let the battery
 run for as long as possible, to maximize the chance of the message
 being delivered.
 
@@ -61,19 +61,19 @@ a) There's no single definition of what "robust" is. It depends on
    a particular application.
 b) Robustness is a complex measure, it doesn't depend on one single
    feature, but rather many different features working together.
-   Consider for example that to make button from the case 2 above
+   Consider for example that to make the button from the case 2 above
    work better, it would help to add a visual feedback, so a user
-   knew what happens.
+   knows what happened.
 
 As you may imagine, umqtt.robust doesn't, and can't, cover all possible
 "robustness" scenarios, nor it alone can make your MQTT application
 "robust". Rather, it's a barebones example of how to reconnect to an
 MQTT server in case of a connection error. As such, it's just one
-of many steps required to make your app robust, and majority of those
+of the many steps required to make your app robust, and majority of those
 steps lie on *your application* side. With that in mind, any realistic
-application would subclass umqtt.robust.MQTTClient class and override
+application would inherit umqtt.robust.MQTTClient class and override
 delay() and reconnect() methods to suit particular usage scenario. It
-may even happen that umqtt.robust won't even suit your needs, and you
+may even be possible that umqtt.robust doesn't suit your needs, and you
 will need to implement your "robust" handling from scratch.
 
 
@@ -82,18 +82,18 @@ Persistent and non-persistent MQTT servers
 
 Consider an example: you subscribed to some MQTT topics, then connection
 went down. If we talk "robust", then once you reconnect, you want any
-messages which arrived when the connection was down, to be still delivered
+messages which arrived when the connection was down, to still be delivered
 to you. That requires retainment and persistency enabled on MQTT server.
 As umqtt.robust tries to achieve as much "robustness" as possible, it
 makes a requirement that the MQTT server it communicates to has persistency
 enabled. This include persistent sessions, meaning that any client
-subscriptions are retained across disconnect, and if you subscribed once,
+subscriptions are retained on disconnectivity, and if you subscribed once,
 you no longer need to resubscribe again on next connection(s). This makes
 it more robust, minimizing amount of traffic to transfer on each connection
 (the more you transfer, the higher probability of error), and also saves
 battery power.
 
-However, not all broker offer true, persistent MQTT support:
+However, not all brokers offer true, persistent MQTT support:
 
 * If you use self-hosted broker, you may need to configure it for
   persistency. E.g., a popular open-source broker Mosquitto requires