FULL-C: time functions - Historie editací

Adamn v 18. 11. 2022, 16:14

2022-11-18T16:14:54Z

Adamn v 17. 11. 2022, 18:13

2022-11-17T18:13:19Z

Adamn v 17. 11. 2022, 18:08

2022-11-17T18:08:00Z

Adamn v 17. 11. 2022, 17:51

2022-11-17T17:51:07Z

Adamn v 17. 11. 2022, 17:50

2022-11-17T17:50:03Z

Adamn v 17. 11. 2022, 17:30

2022-11-17T17:30:19Z

Adamn v 17. 11. 2022, 17:28

2022-11-17T17:28:20Z

Adamn v 11. 7. 2022, 15:58

2022-07-11T15:58:59Z

Adamn v 11. 7. 2022, 15:52

2022-07-11T15:52:04Z

Adamn v 11. 7. 2022, 11:38

2022-07-11T11:38:06Z

@@ Řádek 179: / Řádek 179: @@
 Je-li předaná hodnota ''epochtime'' nenulová, je použita tato hodnota prioritně (a eventuální obsah ''timeptr'' je ignorován).
-Hodnota ''epochtime'' je zpracována (uvnitř SDS) zcela identickým postupem, jako kdyby byla poskytnuta jako odpověď z NTP serveru.
+Hodnota ''epochtime'' je zpracována (uvnitř SDS) zcela identickým postupem, jako kdyby byla poskytnuta jako odpověď z NTP serveru. Tedy dojde k zápisu do RTC bloku, který dále drží běžící čas (vychází z tohoto nového nastavení).
-Obsah ''timeptr'' je přímo zapsán do registrů RTC bloku, který tedy tímto převezme všechny časové (a datumové) údaje a pokračuje od tohoto momentu s těmito údaji.
+Pokud je požadováno zpracovat obsah ''timeptr'' (tzn. epochtime je předán jako 0, a timeptr je platný ukazatel na strukturu), je ''timeptr'' v rámci této funkce převeden na epoch time, a ten je pak zapsán RTC bloku, který tedy tímto převezme všechny časové (a datumové) údaje a pokračuje od tohoto momentu s těmito údaji.
 Návratové hodnoty:
 *  0 = vše OK
 * -1 = chyba (neprovedeno)

@@ Řádek 89: / Řádek 89: @@
 V případě, že dojde k restartu SDS samotného (např. změna konfigurace), tedy pouze měkkému restartu (bez výpadku napájení), tak v RTC zůstává platný čas, který je pak k dispozici ihned po naběhnutí systému. Pokud však nebylo RTC včas naplněno, tak není platný čas k dispozici, a čeká se (typicky max. do 15 sekund od startu) na dotaz a odpověď od NTP serveru (která RTC naplní a to pak čas udržuje dál).
-Upozorňuji na dva typy interních RTC v SDS modulu. Pouze modul typu "SDS-BIG2-DP-DS84" má RTC zálohované baterií, ostatní moduly ne. Proto, pokud potřebujete funkci zálohovaného RTC i u ostatních modulů SDS, musíte připojit externí doplňující RTC (viz nabídka doplňujících modulů), a doplnit si potřebnou obsluhu do svého programu.
+Upozorňuji na dva typy interních RTC v SDS modulu. Pouze modul typu "SDS-BIG2-DP-DS84" má RTC zálohované baterií, ostatní moduly mají RTC v provozu pouze po dobu kdy je modul napájen. Proto, pokud potřebujete funkci zálohovaného RTC i u ostatních modulů SDS, musíte připojit externí doplňující RTC (viz nabídka doplňujících modulů), a doplnit si potřebnou obsluhu do svého programu.
 Paralelně s tímto je v SDS udržováno počítadlo "doby běhu od spuštění" tzv. UpTime. Toto počítadlo se nuluje při každém restartu firmware (libovolný důvod), a také při překročení hodnoty (počítá do 2^32).

@@ Řádek 73: / Řádek 73: @@
      .   .                                                                 .
      .  \./                                                                \./
-  +------------------------------------+                           +----------------+                +-----------+
+  +------------------------------------+    (dorazila odpověď)     +----------------+                +-----------+
-  |  pravidelné dotazy na NTP server   |    "epoch NTP UTC čas"    | interní HW RTC |   při dotazu   | + offset  |
+  |  pravidelné dotazy na NTP server   |    "epoch NTP UTC čas"    | interní HW RTC |    při čtení   | + offset  |
   | (provádí SDS NTP klient)           |-------------------------->| v SDS modulu   | -------------->| + DST     |
   +--+---------------------------------+                           +----+-----------+                +---+-------+
      |                                                                  |                                |
      +----> GET index 44 : stav                                         +----> GET index 139 : epoch     +----> GET index 4 : local time (modified epoch)
-                                                                                                                   indexy 5 .. 11 : local time (items)
+                                                                              (vrací aktuální UTC)                 indexy 5 .. 11 : local time (items)
-Program tedy může sledovat, jestli se povedlo přes NTP protokol získat čas z NTP serveru. Dále může program sledovat, jestli po zapnutí se povedlo z interního HW RTC (vnitřní RTC v základu SDS) získat čas (např. pokud SDS prošlo restartem, je čas zachován).
+Program tedy může sledovat, jestli se povedlo, přes NTP protokol, získat čas z NTP serveru. Dále může FULLC program sledovat, jestli po zapnutí se povedlo z interního HW RTC (vnitřní RTC v základu SDS) získat čas (např. pokud SDS prošlo restartem, je čas zachován).
 Interní RTC v SDS automaticky udržuje běžící platný aktuální čas. Pravidelně je aktualizováno z NTP serveru (typicky vždy co 17 minut, je zaslán dotaz na server). Aktuální čas v době mezi dotazy na NTP server je právě udržován automaticky v bloku RTC. Z tohoto bloku je aktuální čas čten při jakémkoliv dotazu na čas.

@@ Řádek 18: / Řádek 18: @@
   POZOR - tato C funkce je dostupná až pro firmware od 17.11.2022
-           int SDS_set_RTC(void * timeptr, unsigned int epochtime);
+           int SDS_set_RTC(unsigned int epochtime, void * timeptr);
 </pre>
@@ Řádek 170: / Řádek 170: @@
 <pre>
-           int SDS_set_RTC(void * timeptr, unsigned int epochtime);
+           int SDS_set_RTC(unsigned int epochtime, void * timeptr);
 </pre>
-* void * timeprt = ukazatel na strukturu typu "struct tm" (viz výše)
+* ''unsigned int epochtime'' = surová UTC+0 hodnota času (EPOCH) (tak jak by přišla z NTP serveru, bez jakýchkoliv aplikovaných offsetů).
-* unsigned int epochtime = surová UTC+0 hodnota času (EPOCH) (tak jak by přišla z NTP serveru, bez jakýchkoliv aplikovaných offsetů).
+* ''void * timeprt'' = ukazatel na strukturu typu "struct tm" (viz výše)
-Hodnota epochtime je zpracována (uvnitř SDS) zcela identickým postupem, jako kdyby byla poskytnuta jako odpověď z NTP serveru.
+Je-li předaná hodnota ''epochtime'' nenulová, je použita tato hodnota prioritně (a eventuální obsah ''timeptr'' je ignorován).
-Obsah timeptr je přímo zapsán do registrů RTC bloku, který tedy tímto převezme všechny časové (a datumové) údaje a pokračuje od tohoto momentu s těmito údaji.
+Hodnota ''epochtime'' je zpracována (uvnitř SDS) zcela identickým postupem, jako kdyby byla poskytnuta jako odpověď z NTP serveru.
 Návratové hodnoty:
 *  0 = vše OK
 * -1 = chyba (neprovedeno)

@@ Řádek 16: / Řádek 16: @@
           void localtime(unsigned int * timer, void * timeptr);
-  POZOR - tyto C funkce jsou dostupné až pro firmware od 17.11.2022
+  POZOR - tato C funkce je dostupná až pro firmware od 17.11.2022
            int SDS_set_RTC(void * timeptr, unsigned int epochtime);
@@ Řádek 74: / Řádek 74: @@
      .  \./                                                                \./
   +------------------------------------+                           +----------------+                +-----------+
-  |  pravidelné dotazy na NTP server   |    "epoch NTP UTC čas"    | interní HW RTC |   zpracování   | + offset  |
+  |  pravidelné dotazy na NTP server   |    "epoch NTP UTC čas"    | interní HW RTC |   při dotazu   | + offset  |
   | (provádí SDS NTP klient)           |-------------------------->| v SDS modulu   | -------------->| + DST     |
   +--+---------------------------------+                           +----+-----------+                +---+-------+
@@ Řádek 83: / Řádek 83: @@
 Program tedy může sledovat, jestli se povedlo přes NTP protokol získat čas z NTP serveru. Dále může program sledovat, jestli po zapnutí se povedlo z interního HW RTC (vnitřní RTC v základu SDS) získat čas (např. pokud SDS prošlo restartem, je čas zachován).
-Upozorňuji na dva typy interních RTC v SDS modulu. Pouze modul typu "SDS-BIG2-DP-DS84" má RTC zálohované baterií, ostatní moduly ne. Proto, pokud potřebujete funkci zálohovaného RTC i u ostatních modulů SDS, musíte připojit externí doplňující RTC (viz nabídka doplňujících modulů), a doplnit si potřebnou obsluhu do svého programu.-
+Interní RTC v SDS automaticky udržuje běžící platný aktuální čas. Pravidelně je aktualizováno z NTP serveru (typicky vždy co 17 minut, je zaslán dotaz na server). Aktuální čas v době mezi dotazy na NTP server je právě udržován automaticky v bloku RTC. Z tohoto bloku je aktuální čas čten při jakémkoliv dotazu na čas.
 Paralelně s tímto je v SDS udržováno počítadlo "doby běhu od spuštění" tzv. UpTime. Toto počítadlo se nuluje při každém restartu firmware (libovolný důvod), a také při překročení hodnoty (počítá do 2^32).
@@ Řádek 162: / Řádek 168: @@
 Funkce má dva parametry, ale zpracován je vždy jen jeden z nich - je to čistě jen proto, aby se nemusely zavádět dvě různé funkce.

@@ Řádek 5: / Řádek 5: @@
 __NOTOC__
- POZOR - tyto C funkce jsou dostupné až pro firmware od 11.7.2022
+Zařízení SDS pracuje s různou reprezentací časové značky - ta může být poskytována a zpracována jako počet sekund od určeného data (tzv. EPOCH čas), nebo v "položkově-rozpadlé" formě ve formě jednotlivých časových údajů (hodina, minuta, sekunda atd.), uložených ve společné struktuře.
 Za účelem převodu jsou k dispozici tyto funkce:
@@ Řádek 70: / Řádek 68: @@
                                                                    +------------------+
                                                                    | přečtení obsahu  |
-                                                                   | RTC po bootu SDS |  (pouze ale pokud v RTC je platný čas - pozor!)
+                                                                   | RTC po bootu SDS |  (pouze ale pokud v interním RTC je platný čas - pozor!)
                                                                    +------------------+
-    ....                                                                 .
+     ...                                                                 .
-     .  .                                                                 .
+     .   .                                                                 .
-     .  .                                                                 .
+     .  \./                                                                \./
   +------------------------------------+                           +----------------+                +-----------+
   |  pravidelné dotazy na NTP server   |    "epoch NTP UTC čas"    | interní HW RTC |   zpracování   | + offset  |
@@ Řádek 162: / Řádek 160: @@
 Společná funkce pro zápis času, do interního RTC v modulu SDS. Zavoláním této funkce jsou zapsány vždy všechny položky (tzn. celý čas a datum), nelze touto funkcí zapisovat jednotlivé položky samostatně.

@@ Řádek 11: / Řádek 11: @@
 Za účelem převodu jsou k dispozici tyto funkce:
 <pre>
   unsigned int mktime(void * timeptr);
           void gmtime(unsigned int * timer, void * timeptr);
           void localtime(unsigned int * timer, void * timeptr);
 </pre>
@@ Řádek 38: / Řádek 46: @@
    };
-* tm_isdst : pouze pro čtení, vyplněno funkcí localtime() a gmtime(), hodnota je ignorována funkcí mktime()
+Detaily:
-* tm_gmtoff : pouze pro čtení, vyplněno funkcí localtime() a gmtime(), hodnota je ignorována funkcí mktime()
+* tm_isdst : pouze pro čtení, vyplněno funkcí localtime() a gmtime(), hodnota je ignorována funkcí mktime() a SDS_set_RTC()
@@ Řádek 46: / Řádek 55: @@
 SDS primárně využívá NTP pro pravidelnou časovou synchronizaci. SDS tedy pravidelně pomocí NTP aktualizuje svůj interní čas, který udržuje platný.
-Interně je čas v SDS udržován jako hodnota EPOCH vůči UTC.
+V základu, interně, je čas v SDS udržován jako hodnota EPOCH (UTC + 0), tedy počet sekund od pevného epoch data.
 Uživatel může nastavit offset (v hodinách) vůči UTC a také zapnout automatický posun pro letní čas (dle pravidel CEST / CET).
-V případě, že nechcete aby SDS využívalo NTP, lze NTP v nastavení vypnout. Čas pak musíte celému systému dodat sami, zápisem do příslušných indexů (viz seznam). Typicky se toto používá pokud získáváte čas z jiných zdrojů (GSM/LTE nebo např. LoRA síť).
+Program může získat z SDS tento základní EPOCH čas (odpovídající 1:1 (bez posunů) tomu co přichází z NTP), nebo tzv. místní (LOKÁLNÍ) čas (což je upravený - posunutý - čas o uživatelem nastavený offset a také o automatický posun letního času).
@@ Řádek 77: / Řádek 118: @@
-== Příklady ==
+== Příklad ==
 Následující příklad přečte UTC EPOCH čas ze systému (index 139) a převede to na jednotlivé položky do struktury tmp (definována jako: struct tm).
@@ Řádek 99: / Řádek 140: @@
 void main(void)
+{
-   unsigned int systemUTC;
+   unsigned int timeUTC;
    struct tm tmp;
-   printf("time converstion test - localtime\n");
+   printf("time conversion test - localtime()\n");
    // get NTP UTC time
-   systemUTC = SDS_get_u32(139);
+   timeUTC = SDS_get_u32(139);
    localtime(&systemUTC, (void *)&tmp);
-   printf("%02u:%02u:%02u\n", tmp.tm_hour, tmp.tm_min, tmp.tm_sec);
+   printf("%02d:%02d:%02d\n", tmp.tm_hour, tmp.tm_min, tmp.tm_sec);
-   printf("%u.%u.%u\n", tmp.tm_mday, tmp.tm_mon+1, tmp.tm_year+1900);
+   printf("%d.%d.%d\n", tmp.tm_mday, tmp.tm_mon+1, tmp.tm_year+1900);
+}
 </syntaxhighlight>

← Starší verze		Verze z 11. 7. 2022, 15:58
Řádek 79:		Řádek 79:
	== Příklady ==		== Příklady ==

−	~~TBD~~	+	Následující příklad přečte UTC EPOCH čas ze systému (index 139) a převede to na jednotlivé položky do struktury tmp (definována jako: struct tm).
		+
		+	<syntaxhighlight lang="c">
		+	struct tm
		+	{
		+	int tm_sec; // seconds after the minute [0-60]
		+	int tm_min; // minutes after the hour [0-59]
		+	int tm_hour; // hours since midnight [0-23]
		+	int tm_mday; // day of the month [1-31]
		+	int tm_mon; // months since January [0-11]
		+	int tm_year; // years since 1900
		+	int tm_wday; // days since Sunday [0-6]
		+	int tm_yday; // days since January 1 [0-365]
		+	//
		+	int tm_isdst; // Daylight Saving Time flag
		+	int tm_gmtoff; // offset from UTC in seconds
		+	};
		+
		+	void main(void)
		+	{
		+	unsigned int systemUTC;
		+	struct tm tmp;
		+
		+	printf("time converstion test - localtime\n");
		+
		+	// get NTP UTC time
		+	systemUTC = SDS_get_u32(139);
		+
		+	localtime(&systemUTC, (void *)&tmp);
		+
		+	printf("%02u:%02u:%02u\n", tmp.tm_hour, tmp.tm_min, tmp.tm_sec);
		+	printf("%u.%u.%u\n", tmp.tm_mday, tmp.tm_mon+1, tmp.tm_year+1900);
		+	}
		+	</syntaxhighlight>

@@ Řádek 11: / Řádek 11: @@
 Za účelem převodu jsou k dispozici tyto funkce:
 <pre>
-  unsigned int mktime(struct tm * timeptr);
+  unsigned int mktime(void * timeptr);
-          void gmtime(unsigned int * timer, struct tm * timeptr);
+          void gmtime(unsigned int * timer, void * timeptr);
-          void localtime(unsigned int * timer, struct tm * timeptr);
+          void localtime(unsigned int * timer, void * timeptr);
 </pre>
@@ Řádek 19: / Řádek 19: @@
 == Struktura "tm" ==
-Struktura je pro účely FULL-C definována takto:
+Položky označené jako " * timeptr " jsou ukazatele na strukturu tm.
    struct tm

← Starší verze		Verze z 11. 7. 2022, 11:38
Řádek 64:		Řádek 64:
	gmtime() provede přímý "čistý" převod, tedy bez aplikace jakýchkoliv offsetů a posunů.		gmtime() provede přímý "čistý" převod, tedy bez aplikace jakýchkoliv offsetů a posunů.

−	localtime() provede to samé co gmtime() ale s aplikací (1) letního času a za (2) nastaveného NTP offsetu. Letní čas je aplikován jen pouze pokud je právě aktivní (indikováno v tm_isdst). Hodnota offsetu je zapsána do tm_gmtoff - jedná se o hodnotu nastavenou uživatelem v administraci (položka "NTP offset").	+	localtime() provede to samé co gmtime() ale s aplikací (1) letního času a za (2) nastaveného NTP offsetu. Letní čas je aplikován jen pouze pokud je právě aktivní (indikováno v tm_isdst, odpovídá hodnotě na indexu 65). Hodnota offsetu je zapsána do tm_gmtoff - jedná se o hodnotu nastavenou uživatelem v administraci (položka "NTP offset") - respektive lze číst jako proměnnou na indexu 26.
		+
		+	Pozn.:
		+	Aktuální systémový lokální čas (tedy UTC čas s aplikací letního času a offsetu) je k dispozici na indexu 4 - a rozpad pak na indexech 5 až 11, viz seznam všech položek.
		+
		+
		+	== Kde je funkce time() ? ==
		+
		+	Funkce time() není v SDS definována, protože UTC čas systému (tedy výstup takovéto funkce) získáte přímo čtením hodnoty na indexu 139.