Knihovna pro ovládání GSM Modulu Cinterion MC75i

(1)

TECHNICKÁ UNIVERZITA V LIBERCI

Fakulta mechatroniky, informatiky a mezioborových studií

Knihovna pro ovládání GSM Modulu Cinterion MC75i

referenční příručka

Liberec 2012 Filip Melík

(2)

1. Definice datových typů

typedef struct {

char key[9];

unsigned char port_addr;

unsigned char bmask;

} IO_ITEM;

Datová struktura IO_ITEM slouží pro uchování uživatelem definovaných vstupů a výstupů, které bude možno nastavovat a číst přes příkazy v SMS zprávě.

• key – řetězec jednoznačně identifikující příslušný vstup/výstup.

• port_addr – fyzická adresa portu mikrokontroléru na které se nachází příslušný vstup/výstup.

• bmask – bitová maska, která z portu zvoleného adresou port_addr, vymaskuje bit na kterém se nachází daný vstup/výstup. Pokud bychom chtěli číst hodnotu celého portu, zvolíme masku 0xFF.

Příklady nastavení lze nalézt v hlavičkovém souboru „sms_inputs_outputs.h“.

Pozn.: Tento soubor také obsahuje definici OUTS_LENGTH, ve které by měl být správně nastaven počet prvků IO_ITEM, které uživatel přidal do pole outs[]. Tato hodnota je poté použita ve funkci ResolveCommand() ve for cyklu, k projití všech uživatelem definovaných vstupů/výstupů a jejich případnému nastavení. Pokud je hodnota OUTS_LENGTH menší než skutečná, nedojde ke kontrole všech uživatelem definovaných vstupů/výstupů. Pokud je větší než skutečná, může dojít k pádu programu!

2. Globální proměnné

• char buffer[BUFFERLENGTH];

buffer slouží jako dočasná paměť pro znaky přijaté z GSM modulu přes sériovou linku, nad kterou pracují téměř všechny funkce knihovny.

Parametr BUFFERLENGTH má ve výchozím stavu délku 220 znaků, což stačí pro příjem SMS standardní délky 160 znaků + je ponechána rezerva pro potřeby knihovny. Délka byla zvolena s ohledem na zachování co největší části paměti RAM procesoru pro uživatelskou aplikaci.

• volatile int rxn;

rxn slouží jako ukazovátko, které indikuje kde se zrovna v bufferu nacházíme (na pozici jakého znaku ukazuje).

Jeho hodnota se mění v přerušovací rutině pro příjem znaku ze sériové linky, dále v některých funkcích knihovny, které využívají sériové linky bez přerušení (polling) a ve funkci pro vymazání bufferu ClearBuffer() .

• char number[14];

number slouží funkcím GetNumberFromSms() a GetCallingNumber() pro uložení telefonního čísla, ze kterého přichází hovor nebo ze kterého byla přijata zpráva SMS

(4)

tak, aby bylo možné k tomuto číslu přistoupit odkudkoli z hostující aplikace. Číslo je uloženo jako řetězec ukončený null-terminating znakem.

• IO_ITEM outs[];

Pole s uživatelskými definicemi vstupů a výstupů, ovladatelných pomocí SMS zpráv.

3. Funkce knihovny

3.1. PowerOnModule

Hlavička: void PowerOnModule(void);

Popis: Zapne GSM modul MC75i.

Argumenty: ^Žádné.

Návratová hodnota: ^Žádná.

Poznámka: V hlavičkovém souboru je třeba definovat výstup mikrokontroléru, kterým se bude modul zapínat.

3.2. ConfigureModule

Hlavička: void ConfigureModule(void);

Popis: Inicializuje některé parametry GSM modulu MC75i tak, aby všechny funkce knihovny fungovaly jak mají.

Návratová hodnota: Návratová hodnota:

Poznámka: Funkce vypne echo (zaslaný AT příkaz neposílá zpět), přepne odpověď na AT příkazy ze slovního formátu na číselný (místo „OK“ posílá „0“ atd.), vybere paměť pro ukládání telefonních čísel a příchozích SMS, zapne ohlašování chyb při neodeslání SMS, zapne SMS text mód a nastaví způsob upozornění při příchozí SMS. Pokud je SIM karta chráněna PIN kódem, tato funkce také provede autentizaci. PIN kód a příznak že je PIN kód použit je pak třeba nastavit v hlavičkovém souboru. Dále je v

hlavičkovém souboru třeba vybrat úložiště pro příchozí SMS a záznamy telefonního seznamu.

3.3. GprsConfig

Hlavička: void GprsConfig(void);

Popis: Nakonfiguruje GPRS připojení pro spojení s internetem.

Poznámka: Nastavení parametrů GPRS připojení se provádí v hlavičkovém souboru.

3.4. FtpConfig

Hlavička: void FtpConfig(void);

Popis: Nakonfiguruje profil internetové služby pro upload dat na FTP server.

(5)

Poznámka: Nastavení parametrů FTP se provádí v hlavičkovém souboru.

3.5. SmtpConfig

Hlavička: void SmtpConfig(void);

Popis: Nakonfiguruje profil internetové služby pro odesílání e-mailů.

Poznámka: Nastavení parametrů SMTP se provádí v hlavičkovém souboru.

3.6. ClearBuffer

Hlavička: void ClearBuffer(void);

Popis: Vymaže buffer pro příjem znaků ze sériové linky (vyplní ho celý null- terminating charakterem '\0' ).

Poznámka: ^Není.

3.7. UartSend

Hlavička: void UartSend(char* string);

Popis: Pošle řetězec uložený v RAM přes sériovou linku bez koncového

<CR><LF>.

Argumenty: string → řetězec k odeslání Návratová hodnota: ^Žádná.

3.8. UartSend_p

Hlavička: void UartSend_p(char flash *string);

Popis: Pošle řetězec uložený v paměti programu přes sériovou linku bez koncového <CR><LF>.

Argumenty: string → řetězec k odeslání Návratová hodnota: ^Žádná.

3.9. SendATCommand_p

Hlavička: int SendATCommand_p

(char flash *command, char includeAT);

Popis: Pošle AT příkaz uložený v paměti programu přes sériovou linku včetně koncového <CR><LF> a čeká na odpověď od GSM modulu.

Argumenty: command → AT příkaz k odeslání, includeAT → boolean přepínač zda na začátek přidat řetězec „AT“ nebo ne (viz poznámka).

Návratová hodnota: Odpověď na AT příkaz:

0 - OK (příkaz proveden bez chyb) 1 - CONNECT (spojení navázáno)

(6)

2 - RING (detekováno vyzvánění)

3 - NO CARRIER (spojení nenavázáno, nebo odpojeno)

4 - ERROR (neplatný příkaz nebo příliš dlouhá příkazová řádka)

6 - NO DIALTONE (špatný mód, vytáčení nemožné, žádný vyzváněcí tón) 7 - BUSY (vzdálená stanice zaneprázdněna)

Poznámka: Význam argumentu includeAT → pokud zavolám funkci s těmito argumenty: SendATCommand_p(PSTR("+CMGR=1"), 1);

tedy includeAT=1, odeslaný příkaz bude mít podobu:

AT+CMGR=1<CR><LF>

pokud includeAT=0, odeslaný příkaz bude mít podobu:

+CMGR=1<CR><LF>, tedy bez „AT „ na začátku.

3.10. IsAllowedCallingNumber

Hlavička: int IsAllowedCallingNumber (void);

Popis: Porovná telefonní číslo volajícího s těmi co jsou uloženy a vrátí 1 pokud je číslo uložené, 0 pokud není.

Návratová hodnota: 1 pokud je číslo uložené, 0 pokud není

Poznámka: Funkci je třeba zavolat v době kdy přichází hovor.

3.11. IsAllowedSmsNumber

Hlavička: int IsAllowedSmsNumber(char* nmbr);

Popis: Porovná telefonní číslo ze kterého přišla SMS s těmi co jsou uloženy a vrátí 1 pokud je číslo uložené, 0 pokud není.

Argumenty: nmbr → číslo ke zkontrolování, musí obsahovat null-terminating charakter Návratová hodnota: 1 pokud je číslo uložené, 0 pokud není

Poznámka: Pomocná funkce, která je volána automaticky z funkce ParseSms() a neměla by být volána samostatně.

3.12. GetNumberFromSms

Hlavička: char* GetNumberFromSms(int index);

Popis: Vyparsuje telefonní číslo z SMS určené argumentem kterou načte do bufferu a po provedení funkce buffer smaže.

Argumenty: Číslo SMS v paměti ze které chceme získat tel. číslo.

Návratová hodnota: Telefonní číslo ze kterého byla přijata SMS zpráva. Toto číslo se také uloží do globální proměnné number a je ukončené null-terminating charakterem.

Poznámka: Toto pomocná funkce je volána automaticky z funkce ParseSms(). Pokud chci funkci použít samostatně, musím nejřív do bufferu nahrát SMS

příkazem AT+CMGR=x, kde x je pozice na které je SMS uložena. Pozor! - pokud SMS na daném indexu neexistuje, program se zacyklí.

3.13. GetCallingNumber

Hlavička: char* GetCallingNumber(void);

(7)

Popis: Získá telefonní číslo volajícího.

Návratová hodnota: Telefonní číslo volajícího. Toto číslo se také uloží do globální proměnné number a je ukončené null-terminating charakterem.

Poznámka: Funkci je třeba zavolat při příchozím hovoru, jinak vrátí null.

3.14. CheckUrc

Hlavička: unsigned char CheckUrc(void);

Popis: Zkontroluje přijatý URC kód (Unsolicited Result Code – pomocí URC dává modul vědět o asynchronních událostech, např. Příchozí hovor nebo sms).

Návratová hodnota: 1 pokud přišla SMS zpráva.

2 pokud přichází telfonický hovor.

3.15. DialNumber

Hlavička: void DialNumber(char* nmbr);

Popis: Uskuteční hlasový hovor na zvolené telefonní číslo a vyčká do spojení, nebo ukončení hovoru.

Argumenty: nmbr → číslo jak otextový řetězec, které chci volat.

3.16. DialNumber2

Hlavička: void DialNumber2(unsigned char index);

Popis: Uskuteční hlasový hovor na telefonní číslo uložené na pozici index a vyčká do spojení, nebo ukončení hovoru.

Argumenty: index → pozice na které je uloženo číslo, které chci volat.

3.17. ParseSms

Hlavička: void ParseSms(unsigned char smsindex);

Popis: Hledá příkazy pro vzdálenou správu v zadané SMS zprávě a předává je k vykonání funkci ResolveCommand().

Argumenty: Pozice na které je uložena SMS zpráva, kterou chci kontrolovat.

Poznámka: Jednotlivé příkazy v SMS se oddělují středníkem. Pro seznam

podporovaných příkazů viz. 3.18.. Pokud posílám SMS z oprávněného čísla, je možné vynechat příkaz PWD

Příklad: Chci modulu poslat SMS z cizího čísla které není uloženo, SMSPIN jsem v hlavičkovém souboru definoval na hodnotu 1234 a mám definovány výstupy LED1 a LED2.

(8)

Chci přidat do oprávněných číslo +420777123456, aby zhasla LED1 a rozsvítila se LED2 a dále chci aby mi modul zavolal zpět, pošlu SMS ve tvaru :

PWD=1234;AAN=+420777123456;LED1=0;LED2=1;CLB;

3.18. ResolveCommand

Hlavička: void ResolveCommand(char* cmdstring, char* parameter);

Popis: Provádí příkazy obsažené v SMS zprávě.

Argumenty: cmdstring → příkaz k vykonání, parameter → parametr příkazu(pokud je).

Návratová hodnota: ^Není.

Poznámka: Příkaz může být s parametrem nebo bez parametru. Pokud nemá parametr, je nutné předat jako argument parameter prázdný řetězec.

Umí přečíst nebo nastavit uživatelem definované vstupy/výstupy (v souboru sms_inputs_outputs.h) tak, že se mu jako argument cmdstring předá název IO a jako parametr buď 1 pro zapnutí, 0 pro vypnutí a ? pro zjištění stavu.

Dále umí zavolat zpět na číslo, ze kterého přišla SMS příkazem „CLB“.

Umí také SMS zprávou přidat číslo do oprávněných příkazem

„AAN=+420777123456“.

Další příkazy dle požadavků uživatele je možné přidat jednoduše modifikací kódu této funkce.

3.19. GetRecievedSmsNumber

Hlavička: int GetRecievedSmsNumber(void);

Popis: Získá pozici v paměti (index) právě přijaté SMS zprávy.

Návratová hodnota: Pozice v paměti přijaté SMS zprávy.

Poznámka: Funkce musí být volána po přijetí nové SMS zprávy. (přijetí URC +CMTI).

3.20. AddAllowedNumber

Hlavička: void AddAllowedNumber(char* nmbr);

Popis: Uloží telefonní číslo mezi oprávněná do paměti zvolené v hlavičkovém souboru.

Argumenty: nmbr → číslo které chci uložit včetně null-terminating charakteru.

Poznámka: Číslo musí být zadáno v mezinárodním tvaru: +420123456789

3.21. WaitForChar

Hlavička: void WaitForChar(char c);

Popis: Pomocná funkce pro internetové služby – čeká než přijde zadaný znak na sériovou linku pomocí pollingu, teprve poté pokračuje vykonávání programu.

Argumenty: c → znak na který čekám.

(9)

Poznámka: Před zavoláním této funkce je třeba vypnout UART RX interrupt (pokud je zapnutý), protože funkce na znak čeká pomocí pollingu.

3.22. SendSms

Hlavička: int SendSms(char* nmbr,char* text);

Popis: Pošle SMS zprávu na vybrané číslo.

Argumenty: nmbr → telefonní číslo příjemce, text → obsah zprávy.

Návratová hodnota: 1 pokud se SMS podařilo odeslat bez chyby, -1 pokud došlo při odesílání došlo k chybě

Poznámka: Oba argumenty musí obsahovat null-terminating charakter.

3.23. SendDtmf

Hlavička: void SendDtmf (char* dtmfstring);

Popis: Pošle zadaný DTMF řetězec druhé straně při probíhajícím hovoru.

Argumenty: dtmfstring → DTMF řetězec který chci odeslat Návratová hodnota: ^Žádná.

Poznámka: Funkce funguje pouze pokud právě probíhá telefonní hovor.

3.24. SendEmail

Hlavička: int SendEmail (char* text,char* addr);

Popis: Odešle e-mail na zadanou e-mailovou adresu.

Argumenty: text → obsah zprávy , addr → e-mailová adresa příjemce.

Návratová hodnota: 1 pokud se e-mail podařilo odeslat.

-1 pokud došlo při odesílání k chybě.

Poznámka: Oba argumenty musí obsahovat null-terminating charakter.

Konfigurace SMTP serveru a jeho parametrů se provádí v hlavičkovém souboru. Maximální délka textu e-mailu je 1500 znaků.

3.25. FtpOpen

Hlavička: void FtpOpen(void);

Popis: Otevře spojení na FTP server. Konfigurace FTP se nachází v hlavičkovém souboru.

Poznámka: Pokud dojde při otevírání spojení k chybě, funkce skončí.

3.26. FtpUpload

Hlavička: void FtpUpload (char* data);

Popis: Odešle textová data na FTP server.

Argumenty: data → řetězec který chci odeslat.

Poznámka: Před voláním této funkce je třeba otevřít spojení funkcí FtpOpen(), jinak

(10)

funkce skončí v nekonečné smyčce.

3.27. FtpClose

Hlavička: void FtpClose(void);

Popis: Zavře spojení na FTP server.

Poznámka: Tato funkce smí být zavolána pouze po funkci FtpUpload(), nebo FtpOpen(), jinak skončí v nekonečném cyklu.

4. Použití knihovny

Pro použití knihovny je třeba v uživatelské aplikaci linkovat soubor "MC75i_GSM.h". Pokud se bude nacházet v adresáři s hlavním projektem stačí do zdrojového kódu přidat řádku:

• #include "MC75i_GSM_CVAVR.h"

Poté je třeba konfigurovat parametry v hlavičkovém souboru dle požadavků uživatelské aplikace.

Nastavit je třeba tyto parametry:

• F_CPU – frekvence použitého krystalu

• BUFFERLENGTH – délka bufferu – nedoporučujeme přednastavenou hodnotu měnit

• USINGPIN – příznak, který udává, zda je použitá SIM chráněná PIN kódem

• PIN – PIN použité SIM karty. (má význam jen pokud je parametr USINGPIN nastaven)

• SMSPIN – uživatelské heslo, které umožní vykonávat SMS příkazy z jiných než uložených čísel

• DATASTORAGE – příznak určující, zda-li se mají přijaté SMS a oprávněná telefonní čísla ukládat do SIM nebo GSM modulu

• RINGTONE_VOLUME – hlasitost vyzváněcího tónu (jen pokud má uživatelská aplikace připojen k GSM modulu reproduktor)

Dále je třeba nastavit pin, který bude zapínat GSM modul (pin mikrokontroléru, který bude připojen na pin IGT GSM modulu) pomocí těchto definic:

• IGT_PORT

• IGT_DDR

• IGT_BIT

V poslední řadě je třeba nastavit parametry internetových služeb, pokud je budeme využívat. V definovaných textových řetězcích, které obsahují parametry služeb, je třeba měnit pouze hodnoty za poslední čárkou v řetězci (hodnoty před poslední čárkou jsou názvy parametrů, které rozeznává GSM modul a pokud by došlo k jejich změně, služby by nefungovaly správně). Povinné jsou pouze parametry označené v komentáři jako MANDATORY, avšak pro správné fungování některých služeb je třeba vyplnit i nepovinné parametry

Po nastavení volitelných parametrů je třeba knihovnu správně inicializovat. Sled volání funkcí pro

(11)

správnou inicializaci by měl vypadat následovně:

UartInit → PowerOnModule → ConfigureModule → GprsConfig → FtpConfig →

→ SmtpConfig → ClearBuffer

Pozn.: Pokud nepoužíváme internetové služby, je možné vynechat volání funkcí GprsConfig, FtpConfig, SmtpConfig.

Ukázku se správným nastavením parametrů a korektním procesem inicializace je možno shlédnout v souboru „MC75i_GSM_CVAVR.h“ a v souboru s ukázkovou demo aplikací

„MC75i_GSM_CVAVR_demo.c“.

Knihovna pro ovládání GSM Modulu Cinterion MC75i

TECHNICKÁ UNIVERZITA V LIBERCI

Fakulta mechatroniky, informatiky a mezioborových studií