Zobrazení zdroje stránky FULL-C: onewire functions

 Tato stránka popisuje programovací jazyk '''FULL-C''', který je dostupný na vybraných zařízeních SDS. 
 Některá zařízení používají SDS-C, pro který máme návody jinde na této WiKi.

== Funkce pro obsluhu a konfiguraci OneWire sběrnic ==
__NOTOC__
Zařízení BIG a BIG2 (a odvozené varianty STSW atd.) obsahují dvě (resp. jednu - STSW) samostatné OneWire sběrnicové mastery. Ty jsou realizováno prostřednictvím dedikovaných OneWire Bus Master chipů.

Program může použít tyto funkce:
<pre>
         void SDS_disable_onewire(void);
         void SDS_rescan_onewire(unsigned int BUSnr);

         void SDS_onewire_config(unsigned int BUSnr, unsigned int Pxxx, unsigned int Pvalue);

         void SDS_onewire_search_bus(unsigned int busID, unsigned int familyID);
</pre>


== Vypnutí všech sběrnic ==

Použijte funkci SDS_disable_onewire(), po zavolání této funkce dojde k vypnutí veškeré související aktivity (obnoví se až po restartu SDS).

Tato funkce je určena pro uživatele modulů SDS-STSW, které nemají osazený chip 1-Wire Master. Jedná se o některé uživatele (OEM integrátoři) tohoto modulu, kteří v zájmu snížení ceny požadali o vynechání HW podpory pro 1-Wire sběrnici (toto snížení ceny se promítne ale pouze od XYZ odebraných kusů).

Funkci '''SDS_disable_onewire()''' je v takovém případě potřeba zavolat hned na začátku FULL-C programu - tím se vyřadí automatické spuštění 1-Wire sběrnice, které se samozřejmě nemůže na omezeném HW (kde chybí 1-Wire Master chip) povést. Dojde tedy k šesti pokusům o navázání komunikace, a všechny logicky selžou - a pro zajištění stabilního provozu, je vhodné tomuto celému procesu jednoduše předejít (touto funkcí).

''Poznámka:'' podobná funkce je k dispozici i pro SD kartu, tedy funkce SDS_disable_sdc(), viz příslušný návod.
Mohou existovat důvody, kdy nechcete, aby SDS obsluhovalo své OneWire sběrnice. Zejména pokud máte SDS kde není fyzicky OneWire sběrnice osazena (speciální OEM varianty), kdy nechcete aby SDS zbytečně čekalo na nalezení Master chipů. 


== Vnucené prohledání sběrnice ==

Typicky se prohledání sběrnice provádí "ručně" tedy uživatelem přes webové rozhraní, z důvodu, že lze kontrolovat zámky jednotlivých pozic.

Mohou existovat důvody, proč by jste chtěli prohledání aktivovat i z programu, potom zavolejte funkci SDS_rescan_onewire(BUSnr).

POZOR! Tato funkce provede odstranění všech (neuzamčených) nalezených OneWire slave chipů z dané sběrnice, a následně provede nové naplnění seznamu těmi chipy, které se povede nově najít. Může dojít ke změně pořadí, počítejte s tím ve svém programu !

POZOR! Pokud chcete jen zjistit přítomnost nějakého chipu s vámi určenou hodnotou FamilyID, použijte funkci SDS_onewire_search_bus() - tato funkce neprovede zásah do seznamu nalezených chipů.


== SDS_rescan_onewire: Naplánování prozkoumání (rescan) OneWire sběrnice ==

Dostupné ve firmware od 06/2022.

Provede zcela stejnou akci, jako je uživatelem stisknuté tlačítko na webovém rozhraní - tedy rescan vybrané sběrnice OneWire.

Spuštění rescanu je časováno, tedy dojde k němu s pevným zpožděním od zavolání této funkce.

* sběrnice A : BUSnr = 0
* sběrnice B (pozor není na SDS-STSW a odvozených): BUSnr = 1

Průběh je potřeba sledovat čtením patřičných indexů (2000 až 3000) pro jednotlivé pozice OneWire zařízení. Každé nalezené OneWire zařízení musí mít platný ROMcode - jinak je ROMcode nulový (= zařízení na dané pozici nenalezeno).

Zavolání funkce (nebo identicky, spuštění rescanu z webového rozhraní), vynuluje obsah index (busA) 2498 nebo (busB) 2996. V okamžiku dokončení rescanu je do tohoto odpovídajícího indexu zapsán výsledek. Váš program tak může čekat, dokud se výsledek v daném indexu neobjeví (nebo dokud nedojde k timeoutu, což si ale musíte ošetřit ve svém programu sami).


Hodnoty 2498 respektive 2996:
* -1 = chyba, rescan se neprovedl
*  0 = neprobíhá rescan
*  1 = čekáme na spuštění rescan (časová prodleva)
*  2 = rescan právě probíhá
*  4 = rescan úspěšně dokončen ale nic nenaleznul
*  8 = rescan úspěšně dokončen a bylo nalezeno alespoň 1 zařízení


Počet nalezených OneWire zařízení viz indexy (busA) 2499 a (busB) 2997.

Rescan lze spustit pouze pokud je sběrnice OneWire povolena, a pouze pokud už systém obsluhy OneWire naběhnul (index 2998 na hodnotě 8).


== Vyhledání vybraného chipu na OneWire sběrnici ==

'''Pouze pro FULL-C verze 0x11 a dále.'''

Nejčastěji je požadavek na okamžité prohledání sběrnice, kdy se hledá, zda-li je připojen specifický OneWire chip. Přitom je zde současně požadavek na to, aby se seznam dříve nalezených OneWire zařízení (např. teploměry) tímto prohledáním nezměnil.

Typické použití je pro realizaci přístupových systémů, kde se sběrnice opakovaně (pořád dokola) (z vašeho FC programu) prohledává, zda-li na sběrnici byl připojen identifikační chip např. typu DALLAS iButton typ DS1990A. Každý takový chip má unikátní ROM code (od výrobce), a tím se dají jednoznačně od sebe chipy odlišit.

Tyto chipy jsou v různé fyzické formě, např. jako nositelná [https://www.onlinetechnology.cz/eshop/zbozi/klicenka-dallas klíčenka Dallas]. Ve vaší aplikaci se pak uživateli poskytne tzv. [https://www.onlinetechnology.cz/eshop/zbozi/ctecka-dallas čtecí hlavice], ke které uživatel přiloží klíčenku (= chip DS1990A).

Existují ale i chipy ve formě součástky (např. SMD pouzdro), které pak jsou umístěny (zapájeny) na nějakém připojeném HW k SDS, a přes OneWire sběrnici můžete snadno identifikovat, jaký HW je právě (krátkodobě či trvale) připojen, a podle toho provést další akce.

Váš FC program tedy periodicky volá funkci SDS_onewire_search_bus(), za účelem detekce připojeného chipu s určeným identifikátorem (FamilyID, konkrétně pro chipy DS1990A je to 0x01). Pokud je na sběrnici chip nalezen, je jeho ROM code zaznamenám do dočasné tabulky (dočasného seznamu), který je přístupný přes určené systémové položky (indexy). Váš program si tento seznam, po provedené aktualizaci, přečte, a vyhodnotí - a podle nalezených ROM code záznamů pak ví, jaký je v té chvíli ke sběrnici připojený chip (nebo více chipů) s daným typem (FamilyID).

V případě realizace přístupového systému, pak typicky váš program má seznam povolených chipů (seznam jejich ROM code, který je zadán např. přes UserWEB webové rozhraní výrobku, nebo chipy jsou "naučeny" prvním přiložením atd.), a pokud později uživatel takový chip ke sběrnici připojí (např. přiloží na čtecí hlavici), tak jej SDS nalezne (váš FC program po zavolání této funkce), a program to pak vyhodnotí (platný/neplatný resp. známý/neznámý, ROM code). Typicky se v případě přiložení chipu aktivuje některé z relé, které pak např. ovládne zámek dveří (v případě přístupového systému) nebo provede jinou akci atd.

TODO příklad FC kódu - chystá se


== Nastavení časovaní pro vybranou OneWire sběrnici ==

'''Pouze pro SDS varianty DS84.'''

'''Pouze pro FULL-C verze 0x11 a dále.'''

SDS moduly, osazené OW Master chipem (typu 84), tedy především BIG2-DP-DS84 (a další), umožňují velice detailní konfiguraci časování průběhů na každé OneWire sběrnici.

Typicky je nastaveno výchozí, ověřené, časování, a není potřeba na toto sahat. Po každém startu (či restartu) SDS modulu je nastaveno právě toto výchozí časování. Ovšem váš FC program může tuto konfiguraci kdykoliv změnit (resp. i jen některý z parametrů).

Změna časování může být potřebná v případě použití netypického zapojení OneWire sběrnice, nebo při pokusu odladit nedokonale fungující sběrnici. Důvodů může být více, a prakticky se vždy bude jednat o nějakou specifickou situaci. Za běžného provozu a správného použití a zapojení OneWire sběrnice, není jakýkoliv důvod časování měnit.

Funkce SDS_onewire_config() má tři parametry.
 BUSnr = číslo sběrnice
 Pxxx  = identifikátor parametru
 Pvalue = nová hodnota parametru

Zavolání této funkce provede okamžitý zápis nové hodnoty daného parametru do určeného OneWire Master chipu. Další zavolání pro změnu jiného parametru, nezpůsobí ztrátu předchozího nastavení - lze tak postupně zavolat tuto funkci pro kterékoliv parametry (v jakémkoliv pořadí) a ty se postupně nastaví a zůstanou použity (až do restartu modulu SDS).

Možné hodnoty:
               | Pvalue | Pvalue |
 Pxxx | význam |   0    |   1    |
 -----+--------+--------+--------+-- ...
  0   | tRSTL  | 440    |
  1   | tMSP   |  58    |
  2   | tW0L   |  52    |
  3   | tREC0  |   2.75 |
  4   | Rwpu   | 500    | 
 
Výchozí tovární Pvalue = (DOPLNIT HODNOTU).

Všechny hodnoty jsou v jednotce [MIKROSEKUNDA], mimo hodnotu Rwpu (weak pull-up resistor), který je v jednotce [OHM].

TODO doplnit tabulku

Pozn. Volání této funkce pro HW který změnu parametrů nepodporuje (tedy SDS který NEMÁ podtyp DS84), nemá význam - nic se neprovede.