Merge pull request #1801 from openaps/peterleimbach-patch-1

Update Releasenotes.md Important comments on v3 versus v1 NS API

docs/EN/Installing-AndroidAPS/Releasenotes.md

@@ -57,7 +57,7 @@ Release date: 23-10-2023
 
 - NS 15 is required
 - While using websockets in NS v3 plugin treatments entered through NS UI (plus button) and other applications using v1 API are not sent to AAPS. This will be fixed in future release of NS. Always use the same client (v1 or v3) in AAPS and AAPSClient until NS fully switch to v3 internaly. The same is valid for AAPS and AAPSClient itself.
-- Websockets in v3 plugin works similiar way to v1 plugin. Without websockets enabled AAPS schedules regularly downloads from NS which should lead to lower power consumption because NS is not permanently connected. On the oposite side it means delays in exchanging data.
+- Websockets in v3 plugin works similiar way to v1 plugin. Without websockets enabled AAPS schedules regularly downloads from NS which should lead to lower power consumption because NS is not permanently connected. On the oposite side it means delays in exchanging data. Please read [here](Important-comments-on-using-v3-versus-v1-API-for-Nightscout-with-AAPS) the important comments from the dev team before you use it!
 - If you are using xdrip as cgm source you must select it again after update due to internal changes
 - Tidepool can be used as a replacement of NS to pass first objective
 - If you send to xDrip+ you must configure xDrip synchronization plugin. In order to receive BGs from AAPS in xDrip it must be selected source "xDrip+ Sync Follower"
@@ -96,6 +96,34 @@ Release date: 23-10-2023
 - tests cleaup @ryanhaining @MilosKozak
 - new 110k+ lines of code, changed 240k lines, 6884 changed files
 
+(Important-comments-on-using-v3-versus-v1-API-for-Nightscout-with-AAPS)=
+### Important comments on using v3 versus v1 API for Nightscout with AAPS
+
+v1 is the old protocol used for exchanging data between NS web site and NS server. It has many limitations
+- v1 sends only 2 days of data
+- v1 send all 2 days data on every reconnection
+- using websockets is mandatory = permanent connection, more battery compsumption
+- during frequent disconnects to NS connection is paused for 15 minutes to prevent high data usage
+
+v3 is new protocol. More safe and efficient
+- while using tokens you can better define access rights
+- protocol is more efficient on both sides (AAPS & NS)
+- It can read up to 3 months of data from NS
+- you can choose to use or to not use websockets on every device (using means faster updates, not using means lower power compsumption, but slower updates ie. minutes)
+- NSClient is not paused on disconnections
+
+LIMITATIONS
+- NS 15 must be used with AAPS 3.2
+- v3 doesn't see updates done by v1 protocol (probably it will be resolved in some future version of NS)
+- in opposite because of old uneffective method of tracking changes v1 see changes done by v3
+- remember NS still uses v1 internaly so far thus is not possible to enter data through NS web UI if you are using v3. You must use AAPSClient on SMS if you want enter data remotely
+
+RECOMMENDED SETTING
+- because of all above you should choose only one method and use it on all devices (remember all other uploaders at time of writing this are using v1). If you decide to go to v3, select v3 in AAPS and all AAPSClients
+- v3 is preffered because of efficiency
+- using websockets or not using with v3 depends on your preference
+- it HIGHLY recommended to let AAPS gather all data and then upload it to NS as a single uploader. All other devices/applications should only read from NS. By doing it you'll prevent conflicts and sync errors. This is valid for getting BG data to NS using Dexcom Share connector etc. too
+
 ## Version 3.1.0
 
 Release date: 19-07-2022