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í).

Vypnutí OneWire je indikováno hodnotou "16" v (u32) indexu "2998".

''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).

Toto prohledání se pracovně nazývá "master rescan".

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, a nic nikde nepřepsat, použijte funkci SDS_onewire_search_bus() - tato funkce neprovede zásah do seznamu nalezených chipů.


== SDS_rescan_onewire: Naplánování vynuceného prohledá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 master 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.

Hodnota parametru:
* 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 '''SDS_rescan_onewire()''' (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).

<u>Hodnoty v indexu 2498, respektive 2996:</u>
* -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'''.

Master 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 základní 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.

Klíčové indexy:
* 2488 .. 2495 = jednotlivé ROM code pro nalezené OW zařízení na sběrnici (A) s daným FamilyID (nebo 0 pro prázdnou pozici), zapsáno vždy jako pole 8 bajtů
* 2496 = počet nalezených OW zařízení na sběrnici (A) s daným FamilyID 
* 2497 = výsledek pokusu prohledat sběrnici (A) - toto vždy sledujte jako první
* 2986 .. 2993 = jednotlivé ROM code pro nalezené OW zařízení na sběrnici (B) s daným FamilyID (nebo 0 pro prázdnou pozici), zapsáno vždy jako pole 8 bajtů
* 2994 = počet nalezených OW zařízení na sběrnici (B) s daným FamilyID 
* 2995 = výsledek pokusu prohledat sběrnici (B) - toto vždy sledujte jako první

Nalezených zařízení může být i mnohem více než osm, a tak je to do indexu (2496, 2994) zapsáno - ale ROM kódy jsou k dispozici pouze pro prvních osm nalezených zařízení (čistě z důvodu paměťového omezení).

<u>Hodnoty v indexu 2497, respektive 2995 :</u>
* -1 = chyba, prohledání se neprovedlo
*  0 = neprobíhá prohledání dané sběrnice
*  1 = čekáme na spuštění prohledání (časová prodleva)
*  2 = prohledání právě probíhá
*  4 = prohledání úspěšně dokončeno, ale nic (s danou FamilyID) nenalezeno
*  8 = prohledání úspěšně dokončeno, a bylo nalezeno alespoň 1 zařízení s určenou FamilyID

Prohledání sběrnice A lze spouštět nezávisle na prohledání sběrnice (B), a naopak. Prohledání pro obě samostatné sběrnice lze spouštět i současně.

Jednoduchý příklad:
<pre>
// onewire DS1990A

void main(void)
{
 unsigned int status;
 unsigned char ROMcode[8];

 printf("START\n");

 while (1)
 {
    // start - bus A - and for DS1990A the FamilID is 0x01
    SDS_onewire_search_bus(0, 0x01);

    // wait for result
    while (1)
    {
      status = SDS_get_u32(2497 );

      if (-1 == status)
      {
        printf("ERROR\n");
        break;
      } else
      if (1 == status)
      {
        printf("WAITING\n");
      } else
      if (4 == status)
      {
        printf("DONE - NONE FOUND\n"); 
        break;
      } else
      if (8 == status)
      {
        printf("DONE - %u FOUND\n", SDS_get_u32(2496 )); 

        SDS_get_a(2488, (void *)ROMcode, 8);

        printf("%02X %02X %02X %02X %02X %02X %02X %02X \n", 
        ROMcode[0], ROMcode[1], ROMcode[2], ROMcode[3],
        ROMcode[4], ROMcode[5], ROMcode[6], ROMcode[7]);

        break;
      }
    }

 }

}
</pre>

'''POZOR''' - prohledání sběrnice přeruší aktuálně probíhající komunikaci s 1-W zařízením. Například, pokud SDS má na určené sběrnici např. teploměry, a právě na některém z teploměrů provádí měření teploty, tak toto bude přerušeno, a měření zahozeno. SDS provede prohledání sběrnice, a pak se teprve vrátí zpět k původní činnosti, která ale bude zahájena znovu. Použití této funkce, pro prohledání sběrnice, je proto potřeba zvážit - respektive navrhnout využití sběrnice A a B tak, aby např. jedna sběrnice byla výhradně určena pro např. teploměrné chipy (které trvale obsluhuje SDS) a druhá pro dočasně připojované čipy (např. přístupové chipy DS1990A), které si neustále prohledává váš FC program. Takto nedojde ke kolizi činnosti na stejné sběrnici, a aktivita na jedné sběrnici nebude přerušována aktivitou na druhé.


== 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.