diff --git a/docs/EN/Usage/Automation.md b/docs/EN/Usage/Automation.md index 4935b858abb2..1974c4cebc33 100644 --- a/docs/EN/Usage/Automation.md +++ b/docs/EN/Usage/Automation.md @@ -2,111 +2,107 @@ ## What is an Automation? -**Automation** is a feature within **AAPS** designed to simplify a user’s **AAPS** management and be personalised to fit within their lifestyle needs. +"**Automation**" is an **AAPS** feature which can simplify a user’s diabetes management by making automatic changes to insulin delivery. **Automations** allow **AAPS** to be highly personalised for individual users. -An **Automation** instructs **AAPS** to carry out a certain action ‘automatically’ and on a regular basis like exercise or eating soon. **Automation** can also be set up to create a rule for a one off event planned into the future, or triggered if the user is located within a certain radius distance of GPS location or WIFI SSID area. +An **Automation** instructs **AAPS** to carry out a specific action, as a result of one or more conditions or triggers. This can be for irregular episodic events, like low or high BG, a set amount of negative IOB. It can also be for recurring events, for example a meal or exercise at a certain time of day, or when the user is located within a certain distance of GPS location or WIFI SSID area. -The primary benefit of **Automation** is to relieve the user from the burden of having to constantly action a **Temp Target** or similar **AAPS** setting. According to research conduct by [*Stanford university*](https://www.stanford.edu/) there are on average per day 180 health decisions that have to be made by a user when living with Type 1 (and discussed further here: https://www.ncbi.nlm.nih.gov/pmc/art Stanford university icles/PMC6286423/#ref4) . **Automations** can therefore help simplify diabetic management by: +There are a wide range of automation options, and users are encouraged to study these within the **AAPS** app, in the automation section. You can also search the **AAPS** user groups on **Facebook** and **Discord** for automation examples from other users. -* **Decrease decision fatigue:** **Automations** can lessen the mental load of constant decision-making and free up the user’s mental energy for other aspects of life. +## How Automation can help -* **Improve adherence:** **Automations** should help ensure **AAPS** is optimised correctly in the future and avoid **Temp Targets** being missed during busy schedules or periods of forgetfulness. We have all been there! +1) **Decreasing decision fatigue:** The primary benefit of **automations** is to relieve the user from the burden of having to make manual interventions in **AAPS**. [Research](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6286423/#ref4) estimates that an average of 180 additional daily decisions have to be made by those living with Type 1 diabetes. **Automations** can lessen the mental load, freeing up the user’s mental energy for other aspects of life. -* **Personalised management:** **Automations** can be tailored to the user’s specific needs and preferences, by creating a rules with **AAPS** that integrate into the user's lifestyle. +2) **Potentially improving glycemic control:** for example, **automations** can help ensure **Temp Targets** are always set when needed, even during busy schedules or periods of forgetfulness. For example, if a child with diabetes has sport scheduled at school on Tuesdays at 10am and Thursdays at 2pm and always needs a high temp target actioned 30 min before these activities, these can be actioned by automation. -* **Promote data-driven decisions:** when data is gathered with **AAPS**, **Automations** will be invoked and make adjustments within the parameters as set by the user. For instance, for predicted low **BG**, the user can set an **Automation** to reduce insulin and raise **BG**. This can lead to better diabetic management. +3) **Enabling AAPS to be highly customised** to be more or less aggressive in specific situations, according to user preference. For example, triggering a temporary reduced profile% for a set period of time if negative **IOB** develops in the middle of the night, indicating that the existing profile is too strong. -The example below illustrates what steps are eliminated by an **Automation** than compared with no **Automation** set up in **AAPS**. The user has set an **Automation** to trigger a 5am ‘Temp Target Exercise’ to ensure their **BG** is at the optimal rate in time for their 6am exercise: +The example below illustrates how an **Automation** can enable steps to be eliminated. The user has set an **Automation** to trigger a 5 am ‘Temp Target Exercise’ to ensure their **BG** and **IOB** are optimal, in preparation for their 6 am exercise: ![Alt text](../images/automation_2024-02-12_20-54-49.png) -However, it's important to remember that: +## Key considerations before starting with Automations -**Automations** are not a replacement for expert guidance and users should consult with their healthcare team. This is particularly so if the user feels the **Automation** is compensating for sub-optimal insulin base settings (discussed further below). +1) Before setting up an **Automation**, you should have reasonable BG control with **AAPS**. **Automations** should not be used to compensate for sub-optimal basal, ISF or ICR settings (discussed further below). Avoid setting an automated **Profile switch** to compensate for BG rises due to _e.g._ food, these are better dealt with via other strategies (SMBs etc). -As with any other technology, **CGMs** or **Pumps** can malfunction: Technical issues or sensor errors could disrupt the **Automation** actions, and will require manual intervention. **AAPS** should be monitored and alarms & notifications responded to. +2) As with any technology, **CGMs** and **Pumps** and **phones** can malfunction: Technical issues or sensor errors can disrupt the **Automation** actions, and manual intervention may be needed. -Before setting up an **Automation**, a user should have a reasonable BG control within their Closed Loop as well as be comfortable with their **Temp Targets** and **Profile** settings and switches. +4) **Requirements for automations are likely to change as routines change**. When changing between work/school/holiday periods, set a reminder in your calendar to review which automations are currently active (they are easy to activate and de-activate). For example, if you go on holiday, and no longer need the automations set up for school sports or daily exercise, or need to adjust the timings. -## Why is Automation when AAPS is in Closed Loop mode? +5) Automations may conflict with each other, and it is good to review any new automation(s) setting carefully in a safe environment, and understand why an automation may or may not have triggered in the way you expect. -Why is **Automation** required if **AAPS** is in **Closed Loop** mode? Because even in **Closed Loop**, the user may require further flexibility to attain optimal **BG** for regular lifestyle events like: -Attending the exercise at a regular time: an **Automation** can be created to _automatically_ to drive **BG** to optimal level; +6) If using Autosense, try to use **Temp Targets** instead of **Profile Switches**. **Temp Targets** do not reset Autosens back to 0. **Profile Switches** reset Autosens. +7) Most automations should only be set for a **limited time duration**, after which **AAPS** can re-evaluate and repeat the automation, if necessary, and if the condition is still met. For example, "start temp target of 7.0 mmol/l for 30 min" or "start profile 110% for 10 min" _and_ "start temp target of 5.0 mmol/l for 10 min". Using automations to create permanent changes (e.g. to stronger %profile) risks hypoglycemia. -Eating a certain meal regular time, an **Automation** can be created to _automatically_ drive **BG** to optimal level; +## When can I start using Automation? +When you start Objective 10. -For low BG, an **Automation** can be created to _automatically_ activate a high **Temp Target** . +## Where are Automations located in AAPS? -## When can I start using Automation? +Depending on your [config builder](../Installing-AndroidAPS/change-configuration.md#config-builder) settings, **Automation** is located either in the ‘hamburger’ menu or as a tab with **AAPS**. -It is recommended that new users do not rush into **Automations* without first dummy testing their proposed rule by activating the ‘notification’ option under ‘Actions’. +## How can I set up an Automation? -This will trigger **AAPS** to first display to the user a notification rather than automating an action. When the user is comfortable that the notification has been triggered at the correct time, the **Automation’s** rule can be updated to replace the ‘Notification’ with a real ‘Action’. +To set up an **Automation** create a ‘rule’ with **AAPS** as follows: -![Alt text](../images/automation_2024-02-12_20-55-05.png) +* Give your ‘rule’ a title; +* Select at least one ‘Condition’; and +* Select one ‘Action’; +* Check the right box to the **Automation** event is ‘ticked’ to activate the automation: -## How to set up an Automation? +![Alt text](../images/automation_2024-02-12_20-55-35.png) -To set up an **Automation** the user must create a ‘rule’ with **AAPS**. To do this the user must action in **AAPS**: -* give their ‘rule’ a title; -* select at least one ‘Condition’; and -* select one ‘Action’; -* check the right box to the **Automation** event is ‘ticked’ to ensure it is activated. +To deactivate an **Automation** rule, untick the box left of the name of the **Automation**. The example below shows an **Automation** entitled ‘Low Glucose TT’ as either activated (‘ticked) or deactivated (‘unticked’). -![Alt text](../images/automation_2024-02-12_20-55-35.png) +![Alt text](../images/automation_2024-02-12_20-56-08.png) -:::{admonition} Important note -:class: note -Automation is still active when the Loop is disabled! -::: +When setting up an automation, you can first test it by activating the ‘notification’ option under "Actions". This triggers **AAPS** to first display a notification rather than actually automating an action. When you are comfortable that the notification has been triggered at the correct time/conditions, the **Automation** rule can be updated to replace the ‘Notification’ with an ‘Action’. -To deactivate an **Automation** rule when Loop is disabled the user should untick the box left of the name of the **Automation** rule. The example below illustration an **Automation** entitled ‘Low Glucose TT’ as be activated (‘ticked) and deactivated (‘unticked’). +![Alt text](../images/automation_2024-02-12_20-55-05.png) -![Alt text](../images/automation_2024-02-12_20-56-08.png) +:::{admonition} Important note +:class: note -## Where are Automations located in AAPS? +Automations are still active when the Loop is disabled! +::: -Depending on the user’s settings in [config builder](../Installing-AndroidAPS/change-configuration.md#config-builder), an **Automation** is located in the ‘hamburger’ menu or as a tab with **AAPS**. ## Safety limits -There are safety limits set as a general rule for **Automations**: +There are safety limits set for **Automations**: -* The glucose value has to be between 72 and 270 mg/dl or 4 and 15 mmol/l. +* The **glucose** value has to be between 72 and 270 mg/dl (or 4 and 15 mmol/l). * The **Profile** percentage has to be between 70% and 130%. * There is a 5 minute time limit between executions of **Automation** (and first execution). +## Correct use of negative values + :::{admonition} Warning :class: warning Please be careful when selecting a negative value in Automation ::: -Caution must be taken when selecting a ‘negative value’ within the ‘Condition’ like "less than" in **Automations**. Selecting ‘less than’ with a negative value will trigger a negative number. For example: +Caution must be taken when selecting a ‘negative value’ within the ‘Condition’ like "less than" in **Automations**. For example: ![Alt text](../images/automation_2024-02-12_20-56-25.png-500x.png) -**Example 1:** Creating a Condition __lesser than -1__ will: +**Example 1:** Creating a Condition **"is lesser than"** "-0.1" will: -* trigger an **Automation** for any number **strictly lesser than** -1. This includes numbers like -2, -3, -4 and so on. +Trigger an **Automation** for any number which is **strictly** less than** -0.1. This includes numbers like -0.2, -0.3, -0.4 and so on. Remember that -0.1 itself **is not** included in this condition. (The condition "is equal or lesser than -0.1" _would_ include -0.1). -It's crucial to remember that -1 itself **is not** included in this condition. +**Example 2:** Creating a Condition "is greater than" -0.1 will: -**Example 2:** Creating a Condition __more than -1__ will: +Trigger an **Automation** for any number which is **greater than** -0.1. This includes numbers like 0, 0.2, 0.4, and any other positive number. -* trigger an **Automation** opposite to Example 1 above. This means the Condition will be trigger any number **greater than or equal to -1**. +It is important to carefully consider the exact intention of your **Automation** when choosing these conditions and values. -This includes numbers like 0, 1, 10, and any other positive number. +## Automation Conditions -It is therefore important to carefully consider the intention of your **Automation** when choosing a value. Selecting the wrong combination could lead to unintended consequences. - -## Condition - -There are various ‘Conditions’ that can be selected by the user in **Automation*. The list below is non exhaustive: +There are various ‘Conditions’ that can be selected by the user. The list below is non-exhaustive: **Condition:** connect conditions @@ -128,7 +124,7 @@ Several conditions can be linked with **Options:** -* in the **config builder** (Automation), the user can select their required location service.. +* in the **config builder** (Automation), the user can select their required location service. **Condition:** location service @@ -166,14 +162,13 @@ Once the ‘Action’ is added, the default values must be changed to the desir ![Alt text](../images/automation_2024-02-12_20-57-29.png) -## Reprioritising Automation rules to improve AAPS’ performance - - The performance of **AAPS** can be affected by the set up arrangement organised for **Automations** rules. **AAPS** will automate the rules created in the order of preference in a sliding scale starting from the top of the user’s **Automation** list. For example, if the ‘low hypoglycemia’ **Automation** is the most preferred **Automation**, above all other rules, then this **Automation** should appear at the top of the user’s **Automation** list as demonstrated below: +## The order of the automations in the list matters + **AAPS** will automate the rules created in the order of preference, starting from the top of the **Automation** list. For example, if the ‘low hypoglycemia’ **Automation** is the most important **Automation**, above all other rules, then this **Automation** should appear at the top of the user’s **Automation** list as demonstrated below: ![Alt text](../images/automation_2024-02-12_20-57-48.png-500x.png) -To reprioritise the **Automation** rules, click and hold the four-lines-button on the right side of the screen and reorganise the **Automations** by moving the rules up or down. +To reprioritise the **Automation** rules, click and hold the four-lines-button on the right side of the screen. Reorder the **Automations** by moving the rules up or down. ![Alt text](../images/automation_2024-02-12_20-58-00.png-500x.png) @@ -183,24 +178,9 @@ To delete an **Automation** rule click on the trash icon. ![Alt text](../images/automation_2024-02-12_20-58-26.png-500x.png) -## Best practice & caveats +## Examples of Automations -* When using **Automation** for the first time, create a new rule, first add a notification only until you are sure the rule is working effectively. Watch the **Automation** results. -* Do not try to make the ‘conditions’ too easy (i.e.: IF BG > 80 mg/dl AND bg < 180 mg/dl) as otherwise it is unlikely the **Automation**will be triggered. This is important if the ‘action’ is a Profile switch! -* Try to use **Temp Targets** instead of **Profile Switches**. -**Temp Targets** do not reset Autosens back to 0. -* Make sure **Profile Switches** are used sparingly and preferably as a last resort. **Profile Switches** renders Autosens useless for a minimum of 6 hours. -* **Profile Switches** will not reset the **Profile** back to the user’s base Profile -* The user must must create another **Automation** rule to revert to the original**Profile**. Otherwise. the user must action the **Profile** switch manually! -* **Profile Switches** actioned by an **Automation** should be used sparingly. Frequent use of **Profile Switches** could be indicative of an underperforming diabetic management due to poor **AAPS** set up. -* There is increased risk of hypoglycemia if the**Profile Switches** does not expire or reset back to the user’s base **Profile**. - - -## Examples of Automations created - -Below are examples of **Automations** created. Further discussion on **Automations** and how users have individualised their **Automation** can be found in Facebook discussions groups or on Discord. - -As explained above, users should style their **Automation** to suit their own demands and needs. The examples below should not be replicated without the user having a good understanding of the rudimentals **Automation**, it's potential impact it can have on their **AAPS** management. The rules should not be replicated by users without dummy testing (as discussed above) and checking if these parameters below are correct for them. Diabetic management varies from user to user, especially in **AAPS**. +Below are examples of **Automations**. Further discussion on **Automations** and how users have individualised their **Automation** can be found in Facebook discussions groups or on Discord. The examples below should not be replicated without the user having a good understanding of how the **Automation** will work. ### Low Glucose Temp Target @@ -214,7 +194,7 @@ This **Automation** triggers an automatic ‘Temp Target Hypo’ when low **BG* This **Automation** has been created for a user who eats their lunch at work around the same time every weekday but triggered only if the user is situated within a set ‘location’. So if the user is not at work one day, this Automation will be activated. -This **Automation** will set a low Temp Target (Eating Soon) at 13:00 to drive ‘BG, to 90mg (or 5 mmls) in preparation for lunch. +This **Automation** will set a low Temp Target (Eating Soon) at 13:00 to drive ‘BG, to 90mg (or 5 mmol/l) in preparation for lunch. The ‘Trigger’ location is set by inputting the latitude and longitude GPS coordinates as below: @@ -248,15 +228,6 @@ Here is the screenshot detailing the **Automation** triggers: ![Alt text](../images/automation_2024-02-12_21-05-16.png-500x.png) -## Incorrect use of Automation - -Using **Automation** incorrectly can lead to difficulties and even danger to the user’s health. Examples for incorrect use are instance: -* Trying to constantly override **AAPS** rather than pause and properly evaluate the users **Profile** and tuning basal, IC etc. -* Setting a **Profile switch** to compensate for the food. -* Setting a **Profile switch** without inputting a duration. -* Creating one way rules (i.e. failing to create another rule in order to undo the original rule). -* Creating long term rules. - ## Automation Logs **AAPS** has a log of the most recent **Automation** triggered at the bottom of the screen under the **Automation** tab. @@ -274,7 +245,7 @@ The **Automation** will: (2) at 03:38 am, the “High carb after low at night” is triggered * time is between 01:05 am and 06:00 am; -* glucose value is greater than 110mg/dl. . +* glucose value is greater than 110mg/dl. The **Automation** will: * change **Profile** to LocalProfile1 (ie: cancel the temporary profile if any) @@ -294,7 +265,7 @@ Check the box to the right of **Automation** event is ‘ticked’ to ensure th Check your rule prioritisation order as discussed above here. -## Alternatives +## Alternatives to Automations -For advanced users, there are other possibilities to automate tasks using IFTTT or a third party Android app called Automate. Some examples can be found here. +For advanced users, there are other possibilities to automate tasks using IFTTT or a third party Android app called Automate.