Libraries

PAWN

Description

Standard library for the rapidM2M Studio ecosphere

BASICS

xdocs:
  • Pawn - Programming Manual
  • Pawn - Pitfalls when coming from C

    • PRE-PROCESSOR

    #options(opt
    Set global compiler options for DLO (pawncc), handed over to the compiler by command line.
    #options is only allowed on the very top of /dlo/main.p and does not support conditional compilation (#if,..)
    opt - any (single) pawncc compiler option as stated in the
    Pawn Programming Manual (page 168) plus encoding= and compiler=
    #options -O3 #options -d1 #options -w219- … similar to #pragma disable warning 219 #options -w219+ … similar to #pragma enable warning 219 #options encoding=latin1*|utf8|cp437|cp1252 … see type string; *) default #options compiler=pawncc-m14.exe
    #if(cond
    cond - either
  • condition using numeric constant
  • defined defname
  • !defined defname
    • #elseif(cond

    similar to #ifdef

    #else(
    #endif(
    #ifdef(defname

    shorthand for

    #if defined defname
    #ifndef(defname

    shorthand for

    #if !defined defname
    #elseifdef(defname

    shorthand for

    #elseif defined defname
    #elseifndef(defname

    shorthand for

    #elseif !defined defname
    #include("filename"

    load an application specific file

    Remind the automaticlly generated loading order:
    1. ~auto.inc
    2. #preinclude
    3. imported libraries
    4. ~auto-xxx.inc
    5. #include
    filename - name of file to include, with optional path relative to DLO folder
    #include "myfile.inc" #include "myfolder/myfile.inc"
    #preinclude("filename"

    load an application specific file ahead of imported libraries

    Typically used to load configurations required by imported libraries. See #include for details.
    It's good practice to use dde/main.dde for configurations by default.Try to use #preinclude exclusively for DLO-only, complex configurations.
    Due to it's global nature, #preinclude is only available in main.p.
    filename - name of file to include, with optional path relative to DLO folder
    #preinclude "appconfig.inc" #preinclude "configs/appconfig.inc"
    #pragma(
    warning - disable/enable compiler warning messages
    #pragma warning push #pragma warning disable 203 #pragma warning enable 205 ..your code.. #pragma warning pop
    error - disable/enable compiler error messages
    #pragma error push #pragma error disable 203 #pragma error enable 205 ..your code.. #pragma error pop
    For further #pragma topics see Pawn reference manual page 116.

    rapidM2M ECOSPHERE

    Description

    Standard library for the rapidM2M Studio ecosphere

    TYPES

    Unicode:
    Complies with UNICODE ISO 10646 UCS-4, usually encoded as utf-8.
    wikipedia
    ANSI:
    Phrase for 8bit character encoding using codepages such as CP-1252.
  • Standard codepages (astr,nstr) reserve the lower character codes 0x01-0x7F for ASCII characters.
  • Custom codepages (cstr) may assign any glyph to any character code.
    • wikipedia
    CP-1252:
    This is the primary codepage used by default → wikipedia.
    It plays an important role to reduce character width to 8bit ANSI encoding and is similar to
  • ISO-8859-1 (aka Latin-1, IBM-819, CP-819) except character codes 0x80-0x9F which are mapped acc. to the table below
  • Unicode character codes 0x01-0xFF except character codes 0x80-0x9F which are mapped acc. to the table below
  • ASCII (which ranges from 0x01-0x7F only)
    • Character codes 0x80-0x9F mapping
    CP-1252 | Unicode CP-1252 | Unicode CP-1252 | Unicode CP-1252 | Unicode
    0x80 U+20ac0x88 U+02c6 ‰0x90 ?0x98 U+02dc ™
    0x81 ?0x89 U+2030 Š0x91 U+2018 ’0x99 U+2122 š
    0x82 U+201a ƒ0x8a U+0160 ‹0x92 U+2019 “0x9a U+0161 ›
    0x83 U+0192 „0x8b U+2039 Œ0x93 U+201c ”0x9b U+203a œ
    0x84 U+201e …0x8c U+0152 Ž0x94 U+201d •0x9c U+0153 ž
    0x85 U+2026 †0x8d ?0x95 U+2022 –0x9d ?
    0x86 U+2020 ‡0x8e U+017d0x96 U+2013 —0x9e U+017e Ÿ
    0x87 U+2021 ˆ0x8f ?0x97 U+2014 ˜0x9f U+0178
    types:
    Numeric typesString typesOther types
  • All parts of an rapidM2M application (DLO,BLO,POV) rely on a common set of data types for internal data exchange and storage.
  • The DDE is the central place to organize the application's internal data structures.
  • Each part of an rapidM2M application has its individual representation of these common types.

    • Numeric types

    All numeric types support by default special signal conditions acc. to NAMUR 43:
  • xx_OF - overflow - signal too high
  • xx_UF - underflow - signal too low
  • xx_SC - short-cut - damaged signal source
  • xx_OL - open loop - line break, no signal
  • xx_NAN - NaN - can not build signal, invalid signal processing results
    • The default POV considers these special conditions in it's rendering, e.g. breaks trend lines.
    The special signal conditions occupy some values of the numeric type. Therefore the effective signal range is limited to xx_LO … xx_HI instead of xx_MIN … xx_MAX which gives the absolute extents of the underlying numeric type.
    typerangenotes
    u8unsigned integer0 … 255 (0xff)
    u160 … 65535 (0xffff)
    u320 … ‭4294967295‬ (0xffffffff)Limited support in DLO (pawn) due to s32 cell size.
    u64Not supported, s64 may be good enough
    s8signed integer-128 … 127
    s16-32768 … 32767
    s32-‭2147483648 … ‭2147483647‬
    s64-9.223e+15 … ‭9.223e+15Limited support in DLO (pawn) due to byte array representation.
    f16floating point±9.76e-4 … ±1.048e+6half precision
    3 significant digits
    f32±1.18e−38 … ±3.4e+38single precision
    approx. 7 signifanct digits
    f64±2.23e−308 … ±1.80e+308double precision
    approx. 16 significant digits

    String types

    All strings reserve character code 0x00 for "terminating zero".
    While POV and BLO have full Unicode support, the DLO may prefer shorter character encodings to simplify string handling.
    Choose your best fitting string type in this order:
    1. astr - if CP-1252 (or some other standard codepage) is good enough for ever
    2. nstr - if CP-1252 is good enough for the moment, but Unicode may be necessary at a later project phase
    3. ustr - if Unicode is required and your DLO routines are able to deal with utf-8 encoded strings
    4. wstr - if Unicode is required and your DLO routines insists on utf-32 encoded strings
    5. cstr - if your DLO prefers 8bit ANSI characters, but is not satisified with standard codepages such as CP-1252

    typeDLO char encoding—S&T*—POV, BLO
    astrANSI CP-1252 or some other standard codepage—ANSI—utf-8
    nstrANSI CP-1252—utf-8**)—utf-8
    cstrANSI any custom codepage—binary—binary-hex
    wstrUnicode utf-32—utf-8**)—utf-8
    ustrUnicode utf-8—utf-8**)—utf-8
    *) S&T … storage and transmission
    **) Flip between nstr, ustr and wstr anytime in later application updates because they all use the same storage format (utf-8).

    Other types

    typerangenotes
    stamp32date & time1sec resolution
    stamp401/256sec resolution
    binbinary blobanonymous collection of bytes (each 0 … 0xff)
    u8

    unsigned integer 8bit

    U8_MAX = 0xFF
    U8_HI = 0xFA
    U8_LO = 0
    U8_MIN = 0
    U8_NAN = 0xFF - not a number
    U8_OF = 0xFE - overflow
    U8_UF = 0xFD - underflow
    U8_OL = 0xFC - open loop
    U8_SC = 0xFB - short circuit
    Sample code
  • Requires ~dde library
    • #config7 test both va u8 vb u8.1 // fixed comma 1 decimal, same as "u8 decpl=1 vscale=0.1"
    // u8 is treated as a pawn cell (aka s32) new test[DDE_test]; // e.g. test{ .va} dde_test_read( test); #log( "test.va=%d", test.va); test.va= test.va + 13; dde_test_write( test);
    // u8 is treated as javascript number console.log( test.va)
    u16

    unsigned integer 16bit

    U16_MAX = 0xFFFF
    U16_HI = 0xFFFA
    U16_LO = 0
    U16_MIN = 0
    U16_NAN = 0xFFFF - not a number
    U16_OF = 0xFFFE - overflow
    U16_UF = 0xFFFD - underflow
    U16_OL = 0xFFFC - open loop
    U16_SC = 0xFFFB - short circuit
    Sample code
    Similar to u8
    u32

    unsigned integer 32bit

    U32_MAX = 0xFFFFFFFF
    U32_HI = 0xFFFFFFFA
    U32_LO = 0
    U32_MIN = 0
    U32_NAN = 0xFFFFFFFF - not a number
    U32_OF = 0xFFFFFFFE - overflow
    U32_UF = 0xFFFFFFFD - underflow
    U32_OL = 0xFFFFFFFC - open loop
    U32_SC = 0xFFFFFFFB - short circuit
    Sample code
    Similar to u8
    Pawn (DLO) natively supports s32 (a "cell") only.Therefore support of u32 is limited and the application has to deal with a negative sign on numbers > 0x7fffffff (u32 MSB == s32 sign bit).
    s8

    signed integer 8bit

    S8_MAX = 127
    S8_HI = 125
    S8_LO = -125
    S8_MIN = -128
    S8_NAN = 127 - not a number
    S8_OF = 126 - overflow
    S8_UF = -126 - underflow
    S8_OL = -127 - open loop
    S8_SC = -128 - short circuit
    Sample code
    Similar to u8
    s16

    signed integer 16bit

    S16_MAX = 32767
    S16_HI = 32765
    S16_LO = -32765
    S16_MIN = -32768
    S16_NAN = 32767 - not a number
    S16_OF = 32766 - overflow
    S16_UF = -32766 - underflow
    S16_OL = -32767 - open loop
    S16_SC = -32768 - short circuit
    Sample code
    Similar to u8
    s32

    signed integer 32bit

    S32_MAX = 2147483647
    S32_HI = 2147483645
    S32_LO = -2147483645
    S32_MIN = -2147483648
    S32_NAN = 2147483647 - not a number
    S32_OF = 2147483646 - overflow
    S32_UF = -2147483646 - underflow
    S32_OL = -2147483647 - open loop
    S32_SC = -2147483648 - short circuit
    This is Pawn's (DLO) built-in native default integer type, also called a "cell".
    // declare an s32 variable new n = 12; // declare a function with s32 parameter and s32 result function( n) { ... return 12; }
    Sample code
    Similar to u8
    s64

    signed integer 64bit

    S64_MAX = 0x7fffffffffffffff
    S64_HI = 0x7ffffffffffffffd
    S64_LO = 0x8000000000000003
    S64_MIN = 0x8000000000000000
    S64_NAN = 0x7fffffffffffffff - not a number
    S64_OF = 0x7ffffffffffffffe - overflow
    S64_UF = 0x8000000000000002 - underflow
    S64_OL = 0x8000000000000001 - open loop
    S64_SC = 0x8000000000000000 - short circuit
    Sample code
    Pawn (DLO) natively supports s32 (a "cell") only. Therefore s64
  • is implemented as binary buffer u8{8}
  • does not support maths
    • #config7 test both va s64 vb s64.6 // fixed comma 6 decimals, same as "s64 decpl=6 vscale=1e-6"
    // s64 is treated as array of 8 bytes new test[DDE_test]; // e.g. test{ .va{8}} dde_test_read( test); #log( "test.va=%02x%02x%02x%02x %02x%02x%02x%02x", test.va{0},...test.va{7}); test.va= s64set( test.va{0}+1); // quick set s64 using an s32 value test.va= S64_OF; // ... or use constants dde_test_write( test);
    // s64 is treated as javascript BigInt console.log( test.va + 100n)
    f16

    half precision float 16bit

    Smallest increment ±5.96e-8
    This implementation differs slightly from IEEE float16 to increase upper limit from 65k to 1040k.
    F16_NAN = 0xffff - not a number
    F16_OF = 0xfffe - overflow
    F16_UF = 0xfffd - underflow
    F16_OL = 0xfffc - open loop
    F16_SC = 0xfffb - short circuit
    F16_INF = 0x7c00 - infinty (positive)
    F16_INFN = 0xfc00 - negative infinity
    F16_ZERO = 0x0000 - positive zero
    F16_ZERON = 0x8000 - negative zero
    Hint: NAMUR constants use a different scheme than f32/f64 do.
    Sample code
    #config7 test both va f16 // hide decimals vb f16.2 // show 2 decimals, same as "f16 decpl=2"
    // f16 is treated as Float:cell (aka f32) new test[DDE_test]; // e.g. test{ Float:.va} dde_test_read( test); #log( "test.va=%f", test.va); test.va= test.va + 1.23; dde_test_write( test);
    // f16 is treated as javascript number console.log( test.va - 9.87)
    Float

    Pawn's native float type

    It's recommended to use alias "f32" instead.
    Notes about typecasting at float()
    float(i)

    explicit typecast to Float:

    i : s32 - integer value to cast
    returns : f32 - casted value
    Pawn applies automatic type cast to f32 if an operation has at least a single float parameter. Therefore an explicit cast using float() can be omitted.
    These operations lead all to correct results:
    new f32:f= asin( 1); new f32:f= asin( 1.0); new Float:f= asin( 1); new Float:f= asin( 1.0);
    new i= 1234; new f32:f= i / 1000.0; new f32:f= 0.001 * i;
    Us this trick to add explicit cast without calling float():
    new a= 30; new c= 100; new f32:f= acos( 1.0 * a / c) // ^-- prefix with dummy multiplyer instead acos( a / c)
    f32

    single precision float 32bit

    F32_NAN = 0x7f800001 - not a number
    F32_OF = 0x7f800002 - overflow
    F32_UF = 0x7f800003 - underflow
    F32_OL = 0x7f800004 - open loop
    F32_SC = 0x7f800005 - short circuit
    F32_INF = 0x7f800000 - infinty (positive)
    F32_INFN = 0xff800000 - negative infinity
    F32_ZERO = 0x00000000 - positive zero
    F32_ZERON = 0x80000000 - negative zero
    The f32 aliases Pawn's (DLO) built-in native default float type, also called a "Float:cell".
    // declare an f32 variable new f32:f = 12.34; // recommended declaration new Float:fa; // alternative, the native pawn way // ^-- note the capitalized "F" ! // declare a function with f32 parameter and f32 result function( f32:f) { ... return 12.34; }
    Notes about typecasting at float()
    Sample code
    Similar to f16
    f64

    precision 64bit float

    F64_NAN = 0x7ff0000000000001 - not a number
    F64_OF = 0x7ff0000000000002 - overflow
    F64_UF = 0x7ff0000000000003 - underflow
    F64_OL = 0x7ff0000000000004 - open loop
    F64_SC = 0x7ff0000000000005 - short circuit
    F64_INF = 0x7ff0000000000000- infinty (positive)
    F64_INFN = 0xfff0000000000000 - negative infinity
    F64_ZERO = 0x0000000000000000 - positive zero
    F64_ZERON = 0x8000000000000000 - negative zero
    This is javascript's (BLO, POV) built-in native number type, as long as no bit operation (v & 7 → u32) or BigInt(v), 1n typecast are applied.
    Sample code
    Pawn (DLO) natively supports f32 (a "Float:cell") only. Therefore f64
  • is implemented as binary buffer u8{8}
  • does not support maths
    • #config7 test both va f64 vb f64.6 // show 6 decimals, same as "f64 decpl=6"
    // f64 is treated as array of 8 bytes new test[DDE_test]; // e.g. test{ .va{8}} dde_test_read( test); #log( "test.va=%02x%02x%02x%02x %02x%02x%02x%02x", test.va{0},...test.va{7}); static f32_= 123.456; f32_ += 1.23; test.va= f64set( f32_); // quick set f64 using an f32 value test.va= F64_OF; // ... or use constants dde_test_write( test);
    // f64 is treated as javascript number console.log( test.va - 12.34)
    stamp32

    seconds since 1999-12-31 00:00:00 UTC

    Based on s32.
    Sample code
    #config7 test both va stamp32 vb stamp32.utc // same as va - "utc" attribute is optional vc stamp32.local // POV renders in localtime (APIs use always UTC)
    // stamp32 is treated as a pawn cell (aka s32) new test[DDE_test]; // e.g. test{ .va} dde_test_read( test); #log( "test.va=%d", test.va); new dt; rM2M_GetDateTime( dt); test.va= dt.timestamp; // or test.va= now(); dde_test_write( test);
    // stamp32 is treated as javascript number console.log( test.va)
    stamp40

    1/256 seconds since 1999-12-31 00:00:00 UTC (extended accuracy)

    Pawn (DLO) natively supports s32 (a cell) only. Therefore stamp40 is implemented as binary buffer u8{5}
     where {0..3}=stamp32, {4}=ticks aka 1/256 fractions of a second
    Sample code
    #config7 test both va stamp40 vb stamp40.utc // same as va - "utc" attribute is optional vc stamp40.local // POV renders in localtime (APIs use always UTC)
    // stamp40 is treated as array of 5 bytes new test[DDE_test]; // e.g. test{ .va{5}} dde_test_read( test); new seconds= stamp40get( test.va); new ticks = stamp40get256( test.va); #log( "test.va=%d.%d", seconds, ticks); new dt; rM2M_GetDateTime( dt); stamp40set( test.va, dt.timestamp, dt.timestamp256); // quick set stamp40 using seconds & ticks vars dde_test_write( test);
    // stamp40 is treated as javascript number console.log( test.va)
    bin

    Binary blob, byte array

    Packs 4 bytes per Pawn "cell". Uses always a full multiple of Pawn "cells" for storage.
  • Use {} (curly braces) for declarations
  • Use "" (double quotes) for literals
    • // declare a bin variable new b{} = {1,2,3,254,255}; // declare a function with a bin parameter and bin result function( bin{10}) { ... return {1,99,255}; } // declare a function with an open length bin parameter function( bin{}, _cellcnt=sizeof bin) { ... }
    Sample code
    #config7 test both va bin 13 // 13 bytes total size
    // bin is treated as unpacked string (aka array of bytes) new test[DDE_test]; // e.g. test{ .va{13}} dde_test_read( test); new s{200}; memtostr( s, test.va, 0, 13); #log( "test.va=%s", s); DDE_test_va_iter() { // iterate over all items of test.va test.va{i} += i; } dde_test_write( test);
    // bin is treated as hex-string const byteArray= test.va.match(/../g).map(h => parseInt(h,16)); const u8Array= new Uint8Array( byteArray); console.log( u8Array);
    string

    Generic string type

    It's meaning varies and depends on the application part where it is referred to
    • DDE - see types overview for comparision
      • astr - ANSI 8bit, typ. CP-1252 - stored as 8bit ANSI
      • nstr - ANSI 8bit CP-1252 - stored as utf-8
      • cstr - ANSI 8bit /w custom codepage - stored as binary
      • wstr - Unicode utf-32 - stored as utf-8
      • ustr - Unicode utf-8 - stored as utf-8
    • DLO (pawn)
      • packed string (ANSI 8bit, typ. CP-1252) - new s{}="abc"
      • unpacked string (Unicode 32bit) - new s{}=''abc''
    • POV, BLO (javascript)
      • javascript string (Unicode) - const s='abc'

    Details about string encoding

    While most parts of the IDE provide full Unicode support, a view corners have limitiations.
    This does usually not limit your application, but effects the way how characters may be represented (glyphs) inside the IDE.
    • codeBed editor → Unicode utf-8
    • pawncc compiler
      • packed strings → CP-1252 *)
      • unpacked strings → Unicode utf-32
    • testBed console and watches → CP-1252 - unknown characters show unexpected glyphs
    *) this behaviour may be overriden by adding a line to dlo/main.p:
    #options encoding=utf8 ..or.. #options encoding=cp437
    or "per source file" codepage control ... !!upcoming, not available yet!!
    #codepage cp437
    astr

    ANSI typ. CP-1252 stored as 8bit ANSI

    Character codes 0x01 … 0xFF are by default assigned to CP-1252 (0x00 is reserved for terminating zero).
    See topics below how to choose some other standard codepage.
    Use this type only if CP-1252 (or some other standard codepage) is good enough for ever.
    See types overview for potential alternatives.
    astr fits perfectly with Pawn's (DLO) built-in packed string type. It packs 4 characters per Pawn "cell", using always a full multiple of Pawn "cells" for storage.
    // declare a packed string variable new str{} = "my string"; // declare a function with packed string parameter and result function( str{10}) { ... return "my string"; }
    The snippets below use two glyphs to clarify the influence of codepages
  • € - Euro, CP-1252 char 0x80
  • ☻ - Smiley, CP-437 char 0x82

    • Default

    Uses codepage CP-1252 at all edges for least efforts.
    Snippets
    #config7 test both va astr.20 // 20 bytes == 20 chars (/w optional terminating zero)
    // packed string containing CP-1252 characters // (others are replaced by '?' during compile) new t[DDE_test]; // #define DDE_test[ .va{}] t.va= "a€☻\x04"; DDE_test_write( t); DDE_test_read( t); #log( "t.va='%s'", t.va);
    // Unicode string (POV/BLO API applies CP-1252/Unicode mapping) const va= 'a€?\u0004';

    Using another standard codepage (static)

    Not available yet - requires MDN-838
    Select an alternative codepage at compile time (supported encodings).
    To find out which codepages are supported just try them with the #codepage xxx statement (see below). If the compiler does not show up with errors, your are fine.
    Snippets
    #config7 test both va astr.20 param1=cp-437 // 20 chars (/w optional terminating zero)
    // ask compiler to use another codepage for this source file's packed strings #codepage cp-437 // packed string containing CP-437 characters // (others are replaced by '?' during compile) new t[DDE_test]; // #define DDE_test[ .va{20+1}] t.va= "a€☻\x04"; DDE_test_write( t); DDE_test_read( t); #log( "t.va='%s'", t.va); // testbed supports CP-1252 only → shows "a?‚\x04"
    // Unicode string (POV/BLO API applies CP-437/Unicode mapping) const va= 'a?☻\u0004';
    Consider that you will see in the testBed the CP-1252 representation of your strings, only!

    Dynamically choosing the codepage

    Not available yet - requires MDN-838
    Change the codepage during application run-time according to some user setting (supported encodings).
    Snippets
    #config7 test both cp astr.20 default="cp-437" va astr.20 param1=%config7%cp // 20 chars (/w optional terminating zero) vb astr.20 param1=%config7%cp
    // since we do not know the effective codepage at compile time it's recommended to // * keep DLO source in default codepage CP-1252 // * encode chars >0x7f as char constants to disable codepage mapping of compiler // none CP-1252 chars are replaced by '?' during compile: new va{} = "a€☻\x04"; // codepage mapping of compiler disabled due to char constants: new vb{} = "a\x80\x82\x04"; // testbed supports CP-1252 only #log( "va='%s'", va); // → shows "a€?\x04" #log( "vb='%s'", vb); // → shows "a€‚\x04"
    // Unicode string (POV/BLO API applies %config7%cp / Unicode mapping) const va= 'a??\u0004'; // │└── set to '?' by DLO compiler: it's working in CP-1252 which does not know '☻' // └─── set to '?' by API: it's working in CP-437 which does not know '€' const vb= 'aNULL☻\u0004'; // └───└── both char's (0x80, 0x82) interpreted in CP-437
    Consider that you will see in the testBed the CP-1252 representation of your strings, only!
    nstr

    ANSI CP-1252 stored as utf-8

    Use this to simplify string handling at DLO for the moment, but stay prepared for Unicode at a later project stage.
    See types overview for potential alternatives.
    Similar to astr, but
  • limited to CP-1252 (e.g. default behaviour)
  • CP-1252 / Unicode mapping applied in DLO and not at POV/BLO API
    • cstr

    ANSI /w custom codepage stored as binary

    Assign any glyphs to character codes 0x01 … 0xFF (0x00 is reserved for terminating zero).
    Use this type only if your DLO prefers 8bit ANSI characters, but is not satisified with standard codepages supported by astr.
    See types overview for potential alternatives.
    This string type requires extended custom support by your application. The codepage may be even dynamic, but the string needs to be treated as binary buffer through out the whole system to avoid conflicts with the default utf-8 interpretation.
    Snippets
    testcstr.20 // 20 bytes == 20 chars (/w optional terminating zero)astr.20 default="my-custom-cp" // cp may be even numeric since you are not bound to standard cp names
    // since custom glyphs are unknown by codebed and testbed, it's recommended to // * keep DLO source in default codepage CP-1252 // * encode chars dfferent from CP-1252 as char constants // none CP-1252 chars are replaced by '?' during compile: new t[DDE_test]; // #define DDE_test[ .va{20+1}] new t.va{} = "a€☻\x80\x82\x04"; // packed string citing any custom glyphs #log( "t.va='%s'", t.va); // console may show unexpected glyphs due to CP-1252 limitation displayWithCodepage( t.va, t.cp); // render custom codepage's glyphs
    t.va= '61803f808204'; // Hex-encoded binary // | | └─└─└─ char constants remain unchainged // | └── ☻ not known in CP-1252 → replaced by '?' // └── € is known by CP-1252 // convert hex-string into array buffer const bin=new Uint8Array( t.va.length/2); for(let i=0;i<t.va.length/2;i++) bin[i]= parseInt( t.va.substr(i*2,2), 16); // map buffer to your custom codepage // just for example we use some standard cp such as 'ibm866' (chich in fact would be better done with astr) const dec= new TextDecoder( t.cp); console.log( dec.decode( bin));
    Consider that you will see in the
    • codeBed the Unicode, and in the
    • testBed the CP-1252
    representation of your strings, which may not correspond with your custom codepage's glyphs!
    wstr

    Unicode utf-32 stored as utf-8

    Use this type only if Unicode is required and your DLO routines insist on utf-32 encoded strings.
    See types overview for potential alternatives.
    wstr fits perfectly with Pawn's (DLO) built-in unpacked string type. It occupies one Pawn "cell" per character (utf-32).
    // declare an unpacked string variable new str[] = ''my €☻''; // declare a function with unpacked string parameter and result function( str[10]) { ... return ''my €☻''; }
    Snippets
    #config7 test both va wstr.20 // 20 bytes (not chars!, /w optional terminating zero)
    // unpacked string containing Unicode utf-32 characters // e.g. "€" == "\x20AC" - // no CP-1252 translation applies like /w packed strings new t[DDE_test]; // #define DDE_test[ .va[20+1]] t.va= ''a€☻\x04''; DDE_test_write( t); DDE_test_read( t); // #log( "t.va='%s'", t.va); // n.a. for unpacked strings
    // Unicode string const va= 'a€☻\u0004';
    ustr

    Unicode utf-8 stored as utf-8

    Use this type only if Unicode is required and your DLO routines (such as display drivers) are able to deal with utf-8 encoded strings.
    See types overview for potential alternatives.
    Snippets
    #config7 test both va ustr.20 // 20 bytes (not chars!, /w optional terminating zero)
    // packed string containing Unicode utf-8 characters *) new va{} = "a\xE2\x82\xAC\xE2\x98\xBB\x04"; // ''a€☻\x04'' displayOut_utf8( va); // use your own display output function // #log( "va='%s'", va); // n.a. for utf-8
    // Unicode string *) const va= 'a€☻\u0004';
    *) Treatement of invalid utf-8 codes 0x80 … 0xBF
    • up-wards: POV/BLO API siltently convert to latin-1 (where 0x80-0x9F are control chars, A0-BF are same as CP-1252)
    • down-wards: DLO always gets well formed uft-8 from POV/BLO API

    HELP

    helpintro:

    Help is written as plain list of keyword definitions.

    Each definition consist of

  • keyword - which may be globally unique
  • description - of (nearby) any HTML content
  • category such as book, category, dpid, apmpartfor structured rendering and automatic cross-references
  • kind - func, const, enum, struct, type, howto,...
  • subdefs - according to it's kind - params, props, consts,...

    • All definitions are collected in a bookbox, which is built from

  • one ".help" file and
  • any optional ".helpinc" files

    • A bookbox always follows this structure

  • book
  • > category
  • >> definitions

    • .book MY BOOK .category FIRST CATEGORY .const - constant definition .type - base type definition .enum - enum type definition .struct - struct type definition .callback - callback type definition .func - function definition .howto - principle definition/description

    The full declaration, including sub-definitions:

    .const MY_CONST=value - constant definition /w optional value assignment .type TmyType:s32 - s32 is an optional underlying base-type ._ const=value - constant value(s) /w optional value assigment .enum TmyEnum:s32 - s32 is an optional underlying base-type ._ const=value - constant value(s) /w optional value assigment .struct TmyStruct - my own structure ._ prop:type - property type(s) ._ name=value - /w optional constant value(s) .callback TmyCallback( param) - my own callback with param // ?param ... optional param // param=77 ... preset (optional) param // ¶m ... output param ._ param:type - parameter type(s) ._ name=value - /w optional constant value(s) ._ :type - "returns" declaration (a param w/o name) ._ name=value - /w optional constant value(s) .func myFunc( param) - my own function // ?param ... optional param // param=77 ... preset (optional) param // ¶m ... output param ._ param:type - parameter type(s); ._ name=value - /w optional constant value(s) ._ :type - "returns" declaration (a param w/o name) ._ name=value - /w optional constant value(s)
    .howto -

    short description of relationships/procedure/principles

    .howto <shortref> - <short description> <description>

    The <description> may contain any HTML tag (see example below),espcially these tags and predefined classes:

  • .important
    This is a very important information for your proggi!
  • .note
    This is some noteable information for your proggi.
  • h5
    Intermediate heading

    Followed by some explanations...


  • #[code <any code>] - inline code
  • .code.dde - code box for DDE
    // This is some DDE source code
  • .code.pawn
  • .code.help
  • .code.js
  • .code.blo.js
  • .code.pov.js
  • .cheatsheet

    • demohelp - DEMONSTRATE HELP DESCRIPTION
    Use for description any PUG syntax feature.

    Save space

  • with interpolated or
  • or block expansion
  • Avoid <u>inline</u> html tags for the sake of escaping!

    • Put a link

  • either asstand alone tag
  • or inline


    • use piped-text to concatenate some more lines to the div

    (Don't forget the spaces then)

    or use a block to easily write multiple lines even with embedded html tags.

    helpconst:
    C1 -

    just declare the constant name

    The following description may consist of any element as described in howto#demohelp

    C2 - 1234

    declare name and it's numeric value

    C3 - "abc"

    declare name and it's string value

    C5 -

    Verbose descriptions

    using

  • any regular
  • html tag(s)
    • s32

    signed integer 32bit

    astr

    ASCII string, C-style with terminating zero

    Tscale

    derived type to give a better explanation ofit's purpose, range,...

    TSCALE_MIN = 1
    TSCALE_MAX = 100
    Txyz

    derived array type

    Terror: s32

    enum definition

    it's recommended to specify a base type such as s32

    Add some type-prefix to the const names, to make them globally unique.
    ERR_A - default value
    ERR_B = 123 - number
    ERR_C = C1 - refer to some const definition
    Txyz:

    3 axis coordinates

    x : s32
    y : s32
    z : s32
    TxyzArray

    array of Txyz with 0+ items

    TxyzArr10

    array of Txyz with 1+ items

    Tmeasurement:

    struct type /w inline const definition

    val : s32 - value
    quality : s32 - measurement quality
    QL_POOR = 1
    QL_GOOD = 5
    QL_BEST = 9
    foo2()

    function w/o params but result

    Optionally indicate wether the function returns some result (used to validate the function's parameter list):
  • .func.fvoid ... no results (void function)
  • .func.freturns ... returns some result
    • returns : s32 - result is the last param and must not have a name
    foo3(a, b="abc", c=)

    function /w params

    a : s32 - mandatory number
    b : astr - optional ascii-string /w default value
    c : s32 - optional number /w auto-default (not recommended)
    returns : Terror - result, e.g. error code
    foo4(cb)

    /w callback parameter

    cb : Tmycallback
    Tmycallback:(a,b)
    a : * - reference value
    b : * - value to compare with reference value
    : bool - true if b >= a
    foo5(out a, out b=)

    /w "out only" params

    The function operates on out parameters like that:

  • incoming values are ignored
  • outgoing values are set
    • a : Txyz - mandatory
    b : Txyz - optional; no output written to this param when missing
    foo6(inout a, inout b=)

    /w "in & out" (by ref) parameters

    The function operates on inout parameters like that:

  • incoming values are used for processing
  • outgoing values are set
    • a : Txyz - mandatory
    b : Txyz - optional
    foo6( &a, &b=){ a= a+b; if (&b) b++; }

    ~stdlib

    Description

    Standard library for the rapidM2M Studio ecosphere

    OVERVIEW

    Abstract:
    This library contains both general functions that are available on all rapidM2M hardware platforms and functions that are only available on specific rapidM2M hardware platforms (e.g. rapidM2M M2). In order for the appropriate hardware-specific functions to be available, you must select the rapidM2M hardware platform installed in your device via the drop-down list "Device profile" in the "Project settings" (e.g. rapidM2M M2 in the case of a rapidM2M C32x).

    Supported rapidM2M hardware platforms:
    If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.

    COMMON

    Terror: s32

    Default return codes for general purposes.

    While values <0 always indicate an error, those >=0 may be used to transport a valid result.
    OK = 0 - Everything fine

    Return codes provided by the rapidm2m device API

    Runtime errors
    ERROR = -1 - Any other error; it's meaning depends on the producing function
    ERROR_PARAM = -2 - Parameter error
    ERROR_UNKNOWN_HDL = -3 - Unknown handler, handle or resource error
    ERROR_ALREADY_SUBSCRIBED = -4 - Already subscribed service or resource error
    ERROR_NOT_SUBSCRIBED = -5 - Not subscribed service error
    ERROR_FATAL = -6 - Fatal error
    ERROR_BAD_HDL = -7 - Bad handle or resource error
    ERROR_BAD_STATE = -8 - Bad state error
    ERROR_PIN_KO = -9 - Bad PIN state error
    ERROR_NO_MORE_HANDLES = -10 - The service subscription maximum capacity is reached
    ERROR_DONE = -11 - The required iterative process is now terminated
    ERROR_OVERFLOW = -12 - The required operation has exceeded the function capabilities
    ERROR_NOT_SUPPORTED = -13 - An option, required by the function, is not enabled on the CPU, the function is not supported in this configuration
    ERROR_NO_MORE_TIMERS = -14 - The function requires a timer subscription, but no more timer resources are available
    ERROR_NO_MORE_SEMAPHORES = -15 - The function requires a semaphore allocation, but there are no more semaphore resources
    ERROR_SERVICE_LOCKED = -16 - The function was called from a low or high level interrupt handler (the function is forbidden in this case)
    ERROR_MEM = -100 - Error allocating memory
    ERROR_SIM_STATE = -101 - Credits of the cloud account are used up; SIM state error
    ERROR_MODEM_DISABLED = -102 - Modem disabled
    ERROR_SENSOR_DISABLED = -102 - Sensor disabled (Alias for ERROR_MODEM_DISABLED)
    ERROR_FEATURE_LOCKED = -103 - Feature locked
    ERROR_TXITF = -104 - Tx interface (uplink) not available (e.g. not opened, currenly closing)

    Return codes provided by the ~stdlib library

    Runtime errors
    ERROR_FULL - bufferfull (e.g. uart)
    Often used by NMEA drivers/decoders
    ERROR_NMEA_DATATYPE - NMEA datatype (e.g. $GGSA) is not supported
    ERROR_NMEA_SENTENCE - NMEA sentence is not valid (e.g. checksum error)
    ERROR_NMEA_LATITUDE - NMEA latitude value is not valid
    ERROR_NMEA_LONGITUDE - NMEA longitude value is not valid
    ERROR_NMEA_ALTITUDE - NMEA altitude value is not valid
    ERROR_NMEA_SATCNT - NMEA number of satellites used is not valid
    ERROR_NMEA_QUALITY - NMEA quality entry is not supported
    ERROR_NMEA_FORMAT - the NMEA frame contains valid, but unexpected data/characters
    Often used by custom driver libraries (or applications)
    ERROR_UNKOWN_PORT - HAL driver does not support given port
    ERROR_CLOSED - Port/resource not opened/initialized yet
    ERROR_TIMEOUT - Some timeout occured
    ERROR_FRAME - Faulty message frame (crc error, invalid content,..)
    ERROR_CRC - More specific alternative to ERROR_FRAME
    errorToStr(err, prefix="")

    Converts any Terror code into a string

    err : Terror - Error code to be converted
    prefix : astr - Text to be placed in front of the error message. - OPTIONAL (Typically used to identify location of the error.)
    returns : astr
  • "ok", if err >= 0 or
  • String (max. 50 characters) consisting of an optionally transferred text followed by the string corresponding to the transferred error code and the error code itself (see Terror).
    • #assert(
    Not available - To generate a compile time assertion, use this snippet instead:
    #if !condition #error message #endif
    Use assert() for run time checks.
    assert(condition=false, ?format, ?params...)

    Shows-up a totally unexpected program behaviour which can be usually caused due to erroneous programming only.

    Any assertion will
  • Stop the program execution and reboot the device
  • Writes information about the assertion into the device registration (RM2M_REG_APP_FLASH). Only information about the most recent assertion can be stored.
  • Generate an error entry in the device log (2999). The parameter of this log entry contains a token that is incremented each time an assertion occurs.
  • Generate an error entry in the device log (3001, SCRIPT ERROR)
  • Popup prominently in TESTbed showing the assertion message as well as the causing file and line number
    • It's recommended to call salve() (or at least setbuf()) to increase the console buffer before using assert().
    DO NOT USE assert to validate user input or any other conditions which may arise due to environmental conditions at runtime.
    Use Pawns's built-in #assert to annotate compile-time assertions.
    condition : bool - The assertion triggers it's message only if the condition is false.
    format : string - Format string as used with #log - OPTIONAL
    params : * - Parameters as used with #log - OPTIONAL
    // generate assertion anyway assert();
    // generate assertion if x not 17 assert( x==17);
    // generate assertion and show expectation assert( x==17, "x is not 17");
    // generate assertion and show expectation + current value assert( x==17, "x expected to be 17, but is %d", x);
    #callback(

    Declares a callback function for library methods such as setInterval.

    Based on the declaration the rapidM2M Studio creates the following:
  • public function "___funcname()"
  • #define "funcname" containing the index of the public function "___funcname()"

  • “funcname” can always be used where the index of a public function is to be passed.
  • To call the function defined here directly, "___funcname()" must be used
    • #callback funcname( params...)
    funcname - Name of the function to be handed over to the library method
    params - Optional parameters as requested by the calling library method

    // Declare callback function #callback my_func() { ...do something... }
    // use with microino methods #callback foo() { #log("test!"); } setTimeout( foo, 1000);
    // use with stdlib methods #callback onRecData( const data[], len, stamp) { #log( "youngest histdata= %s", stampToISOString( stamp)); } main() { catch( rM2M_ReadData( -1, onRecData)); }
    For direct call, prefix the callback name with 3 underscores:
    #callback test() { #log( "tick"); setTimeout( test, 1000); // use as callback for repeated call } ___test(); // direct call
    #error(
    Generates a compile time error.
    To generate a run time error, use #log with an exclamation mark ('!') in front of your message.
    #log( "!my run time error message");
    #warning
    #warning(
    Generates a compile time warning.
    To generate a run time warning, use #log with a question mark ('?') in front of your message.
    To disable warnings use #pragma
    #log( "?my run time warn message");
    #error

    CONSOLE

    #log(format[], {Float,Fixed,_}:...)

    Output a line to the console

    Using #log instead of print/printf brings several advantages:
  • Shows reference to source code location in TESTbed's console
  • Appends \\n automatically at the end of a line
  • Compatible with #watch and assert
  • Takes even huge strings and sends them chunk by chunk without losses
  • Indication in the TESTbed console in case of buffer overflow
    • It's recommended to call salve() (or at least setbuf()) to increase the console buffer before using #log().
    Do not mix #log with print/printf as this may result in unpredictable character sequence.
    format : astr - Format string (C-style formatting codes) as used with printf(). The start-character may give some special meaning:
  • '~' … debug message (light gray font)
  • '!' … error message (red highlighted)
  • '?' … warning message (yellow highlighted)
  • '§' … generates an assertion similar to "assert( false, format, params...)" (red highlighted, bold font)
  • '$' … debug message (green highlighted)
  • any other … regular log message (black font)
    • ... : s32|f32|astr - Additional arguments.
    Depending on the format string, the function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.
    #watch(name_val[], {Float,Fixed,_}:...)

    Shows a value in TESTbed's watch panel. Adds the watch to TESTbed, showing its recent value and stamp.

    The "fetch watch changes" button can be used to also display the value in the console. In the watch panel only the last value is displayed, whereas in the console a separate line (value and associated time stamp) is created for each change.
    It's recommended to call salve() (or at least setbuf()) to increase the console buffer before using #watch().
    name_val : astr - Format string similar as used with printf(). Use the following style for the watch format character string: "name=value"
    name - Identifier of the watch output (no format specifier are allowed in this part of the format string)
    ' = ' - Separator between "Identifier" and "Value". Mandatory!!
    value - Value of the watch output. (format specifier such as %d are allowed in this part of the format string)
    ... : s32|f32|astr - Additional arguments.
    Depending on the format string, the function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the "value" part of the format string.
    Do not combine with print/printf (use #log instead)!
    #watch( "mywatch1=123"); // static number #watch( "mywatch2=susi"); // static string #watch( "mywatch3=%d %s", 123, "susi"); // dynamic mixed value (taken from params)
    catch(err, xe=0, xs="")

    If the Terror passed as parameter "err" indicates an error (i.e. err < 0), a corresponding error message is output via the console. However, using the parameter "xe" a single terror code can be excluded from being reported. Using the parameters "xe" and "xs", a customer-specific error message can be generated for a single terror code.

    The conversion of the Terror code into a string is similar to that of the function errorToStr().
    Depending on the severity of the code it may result in a warning, alert or assertion with optional system hold.
    To maintain execution upon heavy faults:

    (those prefixed with § assertion symbol)

    catchHoldOnAssert= 1; // 1: catch() maintains execution in case of heavy faults // 0: catch() stops execution in case of heavy faults
    err : Terror - Error code to be checked and for which a corresponding error message is output via the console, if necessary.
    xe : Terror - Error code to be treated specifically - OPTIONAL
    The treatment depends on the parameter "xs":
  • If "xs" is not used: Specified error code is excluded from the reporting.
  • If "xs" was specified: For the specified error code the default error message is replaced by the text transferred as parameter "xs".
    • xs : astr - Customer-specific error message to be used for the error code specified by the "xe" parameter. - OPTIONAL
    returns : Terror - Error code passed as parameter "err" ("err" is not modified by the function)
    setbuf(buf{}, size)

    Provides the firmware with a buffer from the RAM area reserved for the device logic that is used to output strings via the printf() function. When this function is called up, the system switches from the 256 byte buffer integrated in the firmware to the transferred buffer.

    The buffer "buf" must be valid during the entire use by the firmware (i.e. it must be defined as a global or static variable).
    buf{} : u8 - Static byte array that should be used as a buffer to output strings
    size : s32 - Size of the buffer in bytes
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - If successful
    ERROR - If not successful
    static con_buf{2048}; // allocate buffer memory setbuf( con_buf, 4*sizeof con_buf); // handover buffer to runtime's console print( "This uses the app's buffer (%d bytes)", 4*sizeof con_buf); setbuf( con_buf, 0); // free buffer (also allowed: "setbuf({0}, 0);")

    TIMER

    rM2M_TimerAdd(funcidx)

    Generates a new 1s timer.

    // Declare callback function // Based on this line, the rapidM2M Studio creates the following: // -) public function "___my_timer_func()" // -) #define "my_timer_func" containing the index of the public function "___my_timer_func()" // // “my_timer_func” can always be used where the index of a public function is to be passed // To call the function defined here directly, "___my_timer_func()" must be used #callback my_timer_func() { ...do something... } // Register timer rM2M_TimerAdd( my_timer_func); // Remove timer rM2M_TimerRemove( my_timer_func);
    funcidx : s32 - Index of the public function that should be called up following expiry of the timer.

    Type of the function:
    public func();
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • No valid index was transferred
  • No further timers can be created (maximum number reached)
  • In the event of an internal error
    • <OK - If another error occurs - see Terror
    rM2M_TimerRemove(funcidx)

    Removes a 1s timer.

    funcidx : s32 - Index of the public function of the timer that should be removed.

    Type of the function:
    public func();
    returns : Terror
    OK - If successful
    ERROR - If no valid index was transferred or in the event of an internal error
    <OK - If another error occurs - see Terror
    rM2M_TimerAddExt(funcidx, bool:cyclic, time)

    Generates a new ms timer.

    The maximum number of simultaneously active ms timers is 8.
    // Declare callback function // Based on this line, the rapidM2M Studio creates the following: // -) public function "___my_timer_func()" // -) #define "my_timer_func" containing the index of the public function "___my_timer_func()" // // “my_timer_func” can always be used where the index of a public function is to be passed // To call the function defined here directly, "___my_timer_func()" must be used #callback my_timer_func() { ...do something... } // Register single shot timer rM2M_TimerAddExt( my_timer_func, false, 333); // Register periodic timer rM2M_TimerAddExt( my_timer_func, true, 2500); // Remove timer rM2M_TimerRemove( my_timer_func);
    funcidx : s32 - Index of the public function that should be called up following expiry of the timer.

    Type of the function:
    public func();
    cyclic : boolean - Setting for the behaviour following expiry of the timer interval:
    true - The timer must be restarted following expiry of the interval.
    false - The timer is stopped following expiry of the interval.
    time : s32 - Timer interval in milliseconds (max. 60,000 ms)
    By setting the interval to 0ms, a timer can be generated for which the call back function is called up immediately after the current code block (e.g. main function) is executed. However, only single shot timers (i.e. the timer is stopped upon expiry of an interval) may be initialised with an interval of 0ms.
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • No valid index was transferred
  • An interval of 0ms was specified and the timer should be restarted automatically upon expiry of the timeout (i.e. cyclical 0ms timer).
  • Internal error
  • No additional timers can be created (maximum number reached).
    • <OK - If another error occurs - see Terror
    rM2M_TimerRemoveExt(funcidx)

    Removes a ms timer.

    funcidx : s32 - Index of the public function of the timer that should be removed.

    Type of the function:
    public func();
    returns : Terror
    OK - If successful
    ERROR - If no valid index was transferred or in the event of an internal error
    <OK - If another error occurs - see Terror
    delay_us(us)

    Blocking delay function. The execution of the device logic is stopped and the following code line is only executed once the delay time has expired.

    us : s32 - Delay time (1...10000 [µs])
    returns : Terror
    OK - If successful
    ERROR - If an error occurs, see Terror

    DATE & TIME

    rM2M_GetTime(&hour=0, &minute=0, &second=0, timestamp=0)
  • If no time stamp was transferred (timestamp=0), the current system time (in UTC) is converted to hours/minutes/seconds.
  • Alternatively, the transferred time stamp is converted to hours/minutes/seconds.
    • hour - Variable to store the hours - OPTIONAL
    minute - Variable to store the minutes - OPTIONAL
    second - Variable to store the seconds - OPTIONAL
    timestamp : stamp32 - Time stamp that should be converted
  • =0 - The current system time (in UTC) is converted.
  • >0 - The transferred time stamp is converted.
    • The time stamp must be specified in seconds since 31.12.1999.
    returns : stamp32
  • timestamp = 0 - Seconds since 31.12.1999 (current system time in UTC).
  • timestamp > 0 - The transferred time stamp is returned.
    • // read current timestamp new timestamp= rM2M_GetTime(); printf( "%d seconds since 1999-12-31 00:00:00", timestamp);
    // read current second only, omit hour and minute new sec; rM2M_GetTime( _,_,sec); printf( "current second is %d", s);
    getRuntime
    rM2M_GetDate(&year=0, &month=0, &day=0, timestamp=0)
  • If no time stamp was transferred (timestamp=0), the date (year, month, day) is determined for the current system time (in UTC).
  • Alternatively, the date (year, month, day) is determined for the transferred time stamp.
    • year - Variable to store the year - OPTIONAL
    month - Variable to store the month - OPTIONAL
    day - Variable to store the day - OPTIONAL
    timestamp : stamp32 - Time stamp for which the date should be determined
  • =0 - The date for the current system time (in UTC) is determined.
  • >0 - The date for the transferred time stamp is determined.
    • The time stamp must be specified in seconds since 31.12.1999.
    returns : stamp32
  • timestamp = 0 - Seconds since 31.12.1999 (current system time in UTC).
  • timestamp > 0 - The transferred time stamp is returned.
    • rM2M_GetDateTime(datetime[TrM2M_DateTime], &isValid=0)

    Reads the current time (in UTC) and date from the system.

    datetime : TrM2M_DateTime - Structure for storing a detailed breakdown of the date and time
    isValid - Will indicate if System Timestamp is valid (set by server) - OPTIONAL
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter was transferred
    getRuntime
    TrM2M_DateTime:

    Detailed breakdown of the date and time

    year : s32 - Year specified relates to the 21st century, i.e. 14 refers to the year 2014
    month : s32 - Month (1..12)
    day : s32 - Day (1..31)
    hour : s32 - Hours(0..23)
    minute : s32 - Minutes (0..59)
    second : s32 - Seconds(0..59)
    DoW : s32 - Weekday (0 = Monday ... 6 = Sunday)
    timestamp : s32 - Time stamp (seconds since 31.12.1999)
    timestamp256 : s32 - Fraction of the next started sec. (resolutions 1/256 sec.)
    TrM2M_DateTime_Flags:

    Control flags for the rM2M_SetDateTime() function.

    RM2M_DATETIME_LOCALTIME = 0b00000001 - Transferred time in local time
    rM2M_SetDateTime(datetime[TrM2M_DateTime], flags=0)

    Sets the system date and time to the values contained in the transferred structure.

    datetime : TrM2M_DateTime - Structure that contains a detailed breakdown of the date and time
  • timestamp = 0 - The values contained in year, month, day, hour, minute and second are used to set the date/time.
  • timestamp != 0 - The time stamp contained in timestamp is used to set the date/time.
    • flags : TrM2M_DateTime_Flags - Configuration flags for setting the system time - OPTIONAL
    Bit0 = RM2M_DATETIME_LOCALTIME - Must be set if the transferred structure contains the time in local time.
    returns : Terror
    >0 - Difference in seconds between the current time and time to be set
    0 - If the difference between the current time and time to be set is less than 5 sec
    ERROR - If invalid parameters were transferred
    ERROR-1 - If the time to be set is more than one day ahead of the current system time
    rM2M_GetTimezoneOffset()

    Returns the difference (in seconds) between the system time (UTC) and local time configured for the site on the rapidM2M Portal server. This can be used to determine the local time in the device logic by adding the difference to the system time (UTC). The offset value is determined by the rapidM2M Portal server in accordance with the set time zone (including summer/winter time) and is synchronised during every connection to the device.

    Example: Central European time (CET = UTC+1) is used for the site -> Offset = 3600 sec.
    new local_time = rM2M_GetTime() + rM2M_GetTimezoneOffset();
    returns : s32 - Offset value in seconds
    rM2M_DoW(timestamp)

    Calculates the weekday from a given timestamp.

    timestamp : stamp32 - Timestamp of the day in question
    returns : s32 - Weekday, 0=Monday ... 6=Sunday

    UPLINK

    rM2M_TxStart(flags=0)

    Triggers a connection to the server with subsequent synchronisation of all memory areas (measurement data, configuration, position data, device log, files,...) between the device and the server. Only those memory areas are transmitted whose content has been changed. If the device is in "online" mode and an active connection to the server is established then this function only triggers synchronisation. The established connection is not disconnected beforehand and then re-established.

    In "online" mode new measurement data that are stored in the internal flash via the rM2M_RecData() function are transferred to the server immediately. Calling the rM2M_TxStart() function is thus not necessary to transfer the measurement data in this case. Calling the function and the related synchronisation of all memory areas after generating every single measurement data record would lead to a much higher volume of data. The same also applies to transfer of the configurations. However it is recommended to call the rM2M_TxStart() function occasionally (e.g. every 2h) even in "online" mode since not all memory areas are automatically synchronised.
    flags : TrM2M_TxStart - Configuration flags for the connection establishment
    RM2M_TX_POSUPDATE = 0b00000001 - If set, the GSM position data is also updated.
    RM2M_TX_REFRESH_CONFIG = 0b00000100 - If set, a connection to the maintenance server is also established.
    RM2M_TX_SUPPRESS_POSUPDATE = 0b00001000 - GSM position data that is automatically executed by the firmware every 24h.
    RM2M_TX_POSUPDATE_ONLY = 0b00010000 - If set, only the GSM position data is updated when a connection is established. Measurement data, configurations etc. are not synchronised.
    RM2M_TX_EVALUATION_ONLY = 0b00100000 - If set, only connection evaluation info is updated when a connection is established. Measurement data, configurations etc. are not synchronised.
    returns : Terror
    OK - If successful
    ERROR_SIM_STATE - If a connection is not possible due to the current SIM state, see TRM2M_SIM_STATE
    ERROR_MODEM_DISABLED - If the connection cannot be established due to the supply voltage being too low
    ERROR_TXITF - If the connection cannot be established due to the TX interface configuration (e.g. TX interface not open)
    <OK - If another error occurs - see Terror
    TrM2M_TxStart:

    Connection flags

    Control flags for the rM2M_TxStart() function
    RM2M_TX_POSUPDATE = 0b00000001 - Update of the GSM position data when establishing a connection.
    RM2M_TX_REFRESH_CONFIG = 0b00000100 - Additionally establishing a connection to the maintenance server.
    RM2M_TX_SUPPRESS_POSUPDATE = 0b00001000 - Suppress update of the GSM position data when establishing a connection.
    This suppresses the update of the GSM position data that is automatically executed by the firmware every 24h.
    RM2M_TX_POSUPDATE_ONLY = 0b00010000 - When establishing a connection, only the GSM position data is updated. Measurement data, configurations, etc. are not synchronised.
    RM2M_TX_EVALUATION_ONLY = 0b00100000 - If set, only connection evaluation info is updated when a connection is established. Measurement data, configurations etc. are not synchronised.
    TrM2M_TxSetMode:

    Communication modes

    Communication modes for the rM2M_TxSetMode() function
    RM2M_TXMODE_TRIG = 0 - Interval
    RM2M_TXMODE_WAKEUP = 1 - Interval & wakeup
    RM2M_TXMODE_ONLINE = 2 - Online
    rM2M_TxSetMode(mode, flags=0)

    Sets the connection type to be used. If the connection type is changed to "Online" or "Interval & wakeup", this is immediately followed by a connection being established incl. a synchronisation with the server, as long as this is not suppressed by the "RM2M_TXMODE_SUPPRESS_SYNC" flags being set. The same also applies to changing the connection type from "Interval" to "Interval & wakeup".

    mode : TrM2M_TxSetMode - Connection type to be used:
    RM2M_TXMODE_TRIG = 0 - The connection is established when the rM2M_TxStart() function is called.
    RM2M_TXMODE_WAKEUP = 1 - The connection is established in the same way as in "Interval" mode when the rM2M_TxStart() function is called. Additionally, the device can be initiated via the server to immediately establish a connection (see
    myDatanet Server Manual ). For this purpose, the device immediately logs into the GSM network as soon as this mode has been set.
    RM2M_TXMODE_ONLINE = 2 - The device does not disconnect the connection and continuously transmits the measurement data. However, every 7 days, the connection is temporarily interrupted in order to verify the server assignment. The connection is established as soon as this mode has been set. Calling the rM2M_TxStart() function is not necessary.
    flags : s32 - Configuration flags for the communication mode
    RM2M_TXMODE_SUPPRESS_SYNC = 0b00000001 - Automatic sync. with the server when the connection type is changed is suppressed
    returns : Terror
    OK - If successful
    ERROR_SIM_STATE - If a connection is not possible due to the current SIM state, see TRM2M_SIM_STATE
    ERROR_MODEM_DISABLED - If the connection cannot be established due to the supply voltage being too low
    ERROR_TXITF - If the connection cannot be established due to the TX interface configuration (e.g. TX interface not open)
    <OK - If another error occurs - see Terror
    Additional explanation about the connection types:

    Connection typeEnergy consumptionData volumesResponse time
    Online*********
    Interval & wakeup*****
    Interval*****
    TrM2M_TxError:

    Connection error codes

    Error codes that are returned by the rM2M_TxGetStatus() function via the optional "errorcode" parameter if the last connection attempt failed.
    General errors
    RM2M_TXERR_NONE = 0 - No error
    RM2M_TXERR_CONNECTION_TIMEOUT - Connection timed out
    RM2M_TXERR_NEWDATA_TIMEOUT - Timeout during server sync in online mode
    RM2M_TXERR_IRREGULAR_OFF - Irregular closed connection
    RM2M_TXERR_SERVER_NOT_AVAILABLE - Server not available
    RM2M_TXERR_SERVER_COMMUNICATION - Error during communication with server
    General modem errors
    RM2M_TXERR_MODEM = 10 - Unspecified modem error
    RM2M_TXERR_MODEM_TIMEOUT - Timeout modem communication
    RM2M_TXERR_MODEM_HW_NOT_FOUND - Modem not found
    RM2M_TXERR_MODEM_HW_UNKNOWN - Unknown modem
    RM2M_TXERR_MODEM_INIT - Error during init
    RM2M_TXERR_MODEM_UNS_RESTART - Unsolicited restart (e.g. due to weak power supply)
    RM2M_TXERR_MODEM_RESETLOOP - Modem reset-loop detected
    RM2M_TXERR_MODEM_UNDERVOLTAGE - Modem undervoltage (power failure) detected
    RM2M_TXERR_MODEM_OVERHEAT - Modem overheat detected
    SIM related errors
    RM2M_TXERR_MODEM_SIM = 30
    RM2M_TXERR_MODEM_SIM_NO_ATTEMPT - Only one remaining pin input attempt
    RM2M_TXERR_MODEM_SIM_PIN_WRONG - Pin code is wrong
    RM2M_TXERR_MODEM_SIM_NO_PIN - Pin code required but not available
    RM2M_TXERR_MODEM_EXTSIM_DENIED - External SIM not allowed (APN and/or feature key)
    RM2M_TXERR_MODEM_EXTSIM_MISSING - External SIM not found
    RM2M_TXERR_MODEM_SIM_OTHER - Any other problem with SIM card (e.g. internal SIM not found)
    Network related errors (GSM, GPRS, PDP, etc.)
    RM2M_TXERR_MODEM_NETWORK = 50 - Unspecified network related error
    RM2M_TXERR_MODEM_GSM_BAND_SEL - GSM not available (e.g. error with antenna)
    RM2M_TXERR_MODEM_NETLOCK - Error registering within network (e.g. not allowed)
    RM2M_TXERR_MODEM_POSUPDATE - Error with GSM position update
    RM2M_TXERR_MODEM_PDP_CTX - Error activating PDP context
    TCP related modem errors
    RM2M_TXERR_MODEM_TCP = 70 - TCP error (e.g. timeout, server not available)
    General WiFi errors
    RM2M_TXERR_WIFI = 200 - Unspecified WiFi error
    RM2M_TXERR_WIFI_TIMEOUT - Timeout WiFi communication
    RM2M_TXERR_WIFI_HW_NOT_FOUND - WiFi device not found
    RM2M_TXERR_WIFI_INIT - Error during init
    RM2M_TXERR_WIFI_IO - Error IO communication
    Network related WiFi errors
    RM2M_TXERR_WIFI_NETWORK = 220 - Unspecified network related WIFI error
    RM2M_TXERR_WIFI_NETWORK_TIMEOUT - Timeout accessing network
    RM2M_TXERR_WIFI_AP_SCAN_TIMEOUT - Timeout scanning for available access points
    RM2M_TXERR_WIFI_AP_SCAN - Error scanning access points (e.g. currently not possible)
    RM2M_TXERR_WIFI_DHCP_TIMEOUT - Timeout receiving IP address from DHCP server
    RM2M_TXERR_WIFI_AP_SETTINGS - Access point settings not plausible
    RM2M_TXERR_WIFI_AP_CONNECT - Error connecting to access point
    RM2M_TXERR_WIFI_AP_NOT_FOUND - Access point not found during scan
    TCP related WiFi errors
    RM2M_TXERR_WIFI_TCP = 240 - Unspecified TCP related WIFI error
    RM2M_TXERR_WIFI_TCP_OPEN_TO - Timeout opening TCP connection
    RM2M_TXERR_WIFI_TCP_SEND_TO - Timeout sending data
    RM2M_TXERR_WIFI_TCP_CONNECT - Error connecting to server
    RM2M_TXERR_WIFI_TCP_FAILED - Other error concerning TCP connection
    General Ethernet errors
    RM2M_TXERR_ETH = 300 - Unspecified Ethernet error
    RM2M_TXERR_ETH_TIMEOUT - Timeout Ethernet communication
    RM2M_TXERR_ETH_INIT - Error during init
    RM2M_TXERR_ETH_IO - Error IO communication
    RM2M_TXERR_ETH_INIT_MAC_PHY - Error initializing MAC/PHY interface
    RM2M_TXERR_ETH_ITF_UP - TCP/IP stack: error bringing itf up (including dhcp)
    Network related Ethernet errors
    RM2M_TXERR_ETH_NETWORK = 320 - Unspecified network related Ethernet error
    RM2M_TXERR_ETH_NETWORK_TIMEOUT - Timeout accessing network
    RM2M_TXERR_ETH_DHCP_TIMEOUT - Timeout receiving IP address from DHCP server
    TCP related Ethernet errors
    RM2M_TXERR_ETH_TCP = 340 - Unspecified TCP related Ethernet error
    RM2M_TXERR_ETH_TCP_OPEN_TIMEOUT - Timeout opening TCP connection
    RM2M_TXERR_ETH_TCP_SEND_TIMEOUT - Timeout sending data
    RM2M_TXERR_ETH_TCP_CONNECT - Error connecting to server
    RM2M_TXERR_ETH_TCP_FAILED - Other error concerning TCP connection
    TrM2M_TxStatus: s32

    Connection status

    Return values of the rM2M_TxGetStatus() function
    RM2M_TX_FAILED = 0b0000000001 - Connection establishment failed (see TrM2M_TxError for details)
    RM2M_TX_ACTIVE = 0b0000000010 - GPRS connection established
    RM2M_TX_STARTED = 0b0000000100 - Connection establishment started
    RM2M_TX_RETRY = 0b0000001000 - Delay until retry
    RM2M_TX_WAKEUPABLE = 0b0000010000 - Modem is logged into the GSM network
    RM2M_TX_EXTSIM = 0b0000100000 - External SIM is used
    RM2M_TX_DISABLED = 0b0001000000 - Modem was deactivated
    RM2M_TX_WAKEUP = 0b0100000000 - Connection establishment triggered by wakeup SMS
    RM2M_TX_POSUPDATE_ACTIVE = 0b1000000000 - Positioning is running
    rM2M_TxGetStatus(&errorcode=0)

    Returns the current connection status.

    errorcode : TrM2M_TxError - Variable to store the error code that occurred during the last connection attempt
    RM2M_TXERR_NONE - Last connection establishment successful
    >RM2M_TXERR_NONE - Last connection establishment failed. For detailed breakdown of the error codes see TrM2M_TxError
    returns : TrM2M_TxStatus
    RM2M_TX_FAILED = 0b0000000001 - Set if the last GPRS connection establishment failed
    RM2M_TX_ACTIVE = 0b0000000010 - Set when a GPRS connection is established
    RM2M_TX_STARTED = 0b0000000100 - Set when a connection establishment has been started
    RM2M_TX_RETRY = 0b0000001000 - Set during the delay until the next automatic retry in the event of connection problems
    RM2M_TX_WAKEUPABLE = 0b0000010000 - Set when the modem is logged into the GSM network (wakeup possible)
    RM2M_TX_EXTSIM = 0b0000100000 - Set if the external SIM is used for the connections
    RM2M_TX_DISABLED = 0b0001000000 - Set if the modem has been deactivated
    RM2M_TX_WAKEUP = 0b0100000000 - Set when a connection establishment was triggered upon receipt of a wakeup SMS
    RM2M_TX_POSUPDATE_ACTIVE = 0b1000000000 - Set when positioning is running
    TrM2M_TxItf: s32

    Available uplink interfaces

    Selectable uplink interfaces for the rM2M_TxSelectItf() function.
    RM2M_TXITF_NONE = 0 - No uplink, communication with the server not possible
    RM2M_TXITF_MODEM = 1 - Mobile network modem
    RM2M_TXITF_WIFI = 2 - WiFi module
    RM2M_TXITF_LAN = 3 - LAN interface
    rM2M_TxSelectItf(itf)

    Selects the communication interface to be used for the uplink.

    itf : s32 - Selection of the communication interface
    RM2M_TXITF_NONE = 0 - No uplink, communication with the server not possible
    RM2M_TXITF_MODEM = 1 - Mobile network modem
    RM2M_TXITF_WIFI = 2 - WiFi module
    RM2M_TXITF_LAN = 3 - LAN interface
    returns : Terror
    OK - If successful
    ERROR - If the selected communication interface is not supported by the device or another error occurs
    TrM2M_TxItfStats:

    Statistical information on the uplink communication interface.

    rtt : s32 - Time [ms] it takes for the device to receive an answer from the server for a keep alive ping sent to the server (round trip time).
    Can only be determined if the "Bidirectional alive ping" is activated on the server. The "Bidirectional alive ping" enables the device and server to easily detect whether the connection is still established. The "Bidirectional alive ping" can be activated globally for the complete server, for a specific customer or for a single site (see myDatanet Server Manual ).
    rM2M_TxItfGetStats(stats[TrM2M_TxItfStats], len=sizeof stats)

    Returns the statistical information about the uplink communication interface.

    stats : TrM2M_TxItfStats - Structure for storing the statistical information
    len : s32 - Size (in cells) of the structure to store the statistical information – OPTIONAL
    returns : Terror
    OK - If successful
    rM2M_SetTCPKeepAlive(time=0)

    Sets the interval at which the keep alive pings are sent during online mode.

    time : u8 - Sets the time between the keep alive pings
    0 - Default setting saved in the firmware is used (15 min. 3 sec.)
    <241 - In 1 sec. increments
    241...255 - In 5 min. increments, whereby 3 sec. is subsequently added
    e.g. 243: 3*5 min. + 3 sec. = 15 min. 3 sec.
    returns : Terror
    OK - If successful
    getRSSI(flags=0)

    Returns the signal strength at the communication interface used for the uplink.

    Falls back to GSM/UMTS/LTE signal strength rM2M_GSMGetRSSI() if current firmware version does not support rM2M_GetRSSI() function.

    flags : s32 - Configuration flags for the signal strength measurement
    RM2M_RSSI_EXTENDED_VALUE = 0b0000000001 - If set, the extended value range for the return of the signal strength is used
    returns : s32 - Signal strength in [dBm]
    RM2M_RSSI_EXTENDED_VALUE not set:
  • Maximum value range: -127 to 127
  • Out of range at: -128
    • RM2M_RSSI_EXTENDED_VALUE set:
  • Maximum value range: -32767 to 32767
  • Out of range at: -32768
    • GSM values range from -113 to -51 dBm.
    UMTS values range from -116 to -54 dBm.
    LTE values range from -141 to -44 dBm.
    When using the LAN interface the return value is 0 dBm.
    It is recommended to use this function instead of rM2M_GetRSSI() and rM2M_GSMGetRSSI()
    rM2M_GetRSSI(flags=0)

    Returns the signal strength at the communication interface used for the uplink.

    It is recommended to use getRSSI() instead of this function.
    flags : s32 - Configuration flags for the signal strength measurement
    RM2M_RSSI_EXTENDED_VALUE = 0b0000000001 - If set, the extended value range for the return of the signal strength is used
    returns : s32 - Signal strength in [dBm]
    RM2M_RSSI_EXTENDED_VALUE not set:
  • Maximum value range: -127 to 127
  • Out of range at: -128
    • RM2M_RSSI_EXTENDED_VALUE set:
  • Maximum value range: -32767 to 32767
  • Out of range at: -32768
    • GSM values range from -113 to -51 dBm.
    UMTS values range from -116 to -54 dBm.
    LTE values range from -141 to -44 dBm.
    When using the LAN interface the return value is 0 dBm.
    It is recommended to use this function instead of rM2M_GSMGetRSSI()
    rM2M_GSMGetInfo(info[TrM2M_GSMInfo], len=sizeof info)

    Returns information on the GSM modem, SIM chip and the GSM network used during the last connection.

    info : TrM2M_GSMInfo - Structure for storing the information, see TrM2M_GSMInfo
    len : s32 - Size (in cells) of the structure to store the information - OPTIONAL
    returns : Terror
    >0 - Size (in cells) of the structure used to store the information
    ERROR - If the address and/or length of the info structure are invalid (outside the device logic data memory)
    <OK - If another error occurs, see Terror
    TRM2M_TX_ACT: s32

    Mobile radio AcT (access technology)

    Mobile radio AcT (access technology) as per 3GPP TS27.007
    RM2M_TX_ACT_GSM = 0 - GSM
    RM2M_TX_ACT_GSM_COMPACT = 1 - GSM compacct
    RM2M_TX_ACT_UTRAN = 2 - UTRAN
    RM2M_TX_ACT_GSM_W_EGPRS = 3 - GSM with EGPRS
    RM2M_TX_ACT_UTRAN_W_HSDPA = 4 - UTRAN with HSDPA
    RM2M_TX_ACT_UTRAN_W_HSUPA = 5 - UTRAN with HSUPA
    RM2M_TX_ACT_UTRAN_W_HSDPA_HSUPA = 6 - UTRAN with HSDPA and HSUPA
    RM2M_TX_ACT_E_UTRAN = 7 - E-UTRAN (LTE including LTE-M)
    RM2M_TX_ACT_EC_GSM_IOT = 8 - EC GSM IOT
    RM2M_TX_ACT_E_UTRAN_NB_S1_MODE = 9 - LTE Cat-NB1
    rapidM2M specific
    RM2M_TX_ACT_WIFI = 100 - WiFi
    RM2M_TX_ACT_ETH = 101 - Ethernet
    RM2M_TX_ACT_UNKNOWN = 255 - Unknown
    TRM2M_SIM_STATE: s32

    SIM state

    Connection can be initiated via device logic
    RM2M_SIM_STATE_NONE = 0 - Initial state
    RM2M_SIM_STATE_PRODUCTION = 1 - Newly produced device is in stock
    RM2M_SIM_STATE_HOT = 2 - Valid contract
    Connection cannot be initiated via device logic
    RM2M_SIM_STATE_COLD = 3 - End of the contract or fair use policy violated
    RM2M_SIM_STATE_DISCARDED = 4 - Device has been decommissioned
    TrM2M_GSMInfo:

    Information regarding the GSM modem, SIM chip and the GSM network used during the last connection.

    cgmi : astr{20} - Manufacturer identification of the modem
    cgmm : astr{20} - Modem model information
    cgmr : astr{20} - Modem revision information
    imei : astr{16} - International mobile equipment identity of the modem (i.e. Modem Serial Number)
    imsi : astr{16} - International mobile subscriber identity of the SIM chip that was used for the last connection. Empty string, if no connection has been established yet.
    iccid : astr{21} - Integrated circuit card identifier of the SIM chip that was used for the last connection. Empty string, if no connection has been established yet.
    mcc : s32 - MCC (Mobile Country Code) of the network used for the last/current connection. 0, if no connection has been established yet.
    mnc : s32 - MNC (Mobile Network Code) of the network used for the last/current connection. 0, if no connection has been established yet.
    simstate : TRM2M_SIM_STATE - Current SIM state
    act : TRM2M_TX_ACT - Radio access technology used for the last/current connection
    lac : s32 - LAC (location area code) of the network used for the last/current connection
    cid : s32 - Cell identifier of the network used for the last/current connection
  • 2G AcT: 16-bit Cell ID
  • 3G AcT: 28-bit UTRAN Cell-Id (16-bit Cell ID + 12-bit RNC-ID)
  • 4G AcT: 28-bit E-UTRAN Cell-Id (8-bit Sector ID + 20-bit eNodeB-ID)
    • rM2M_TxGetLteEvalInfo(info[TrM2M_TxLteEvalInfo], len=sizeof info)

    Returns LTE connection evaluation info.

    info : TrM2M_TxLteEvalInfo - Structure for storing the information, see TrM2M_TxLteEvalInfo
    len : s32 - Size (in cells) of the structure to store the information - OPTIONAL
    returns : Terror
    >0 - Size (in cells) of the structure used to store the information
    ERROR - If the address and/or length of the info structure are invalid (outside the device logic data memory)
    TrM2M_TxLteEvalInfo:

    LTE connection evaluation information.

    timestamp : s32 - Timestamp in [s] of evaluation data.
    commandResult : s32 - Result of the Modem specific evaluation command.
    RRCState : s32 - RRC Connectíon. See TRM2M_TXEVAL_RRCSTATE.
    energyEstimate : s32 - Relative estimated energy consumption of data transmission compared to nominal consumption. See TRM2M_TXEVAL_ENERGY_EST.
    rsrp : s32 - Reference Signal Received Power in [dBm].
    rsrq : s32 - Reference Signal Received Quality in [dB].
    snr : s32 - Signal-to-Noise Ratio in [dB].
    cellId : s32 - Cell Id.
    mcc : s32 - Mobile Country Code.
    mnc : s32 - Mobile Network Code.
    physCellID : s32 - Physical cell ID of evaluated LTE cell.
    earfcn : s32 - EARFCN as defined in 3GPP TS 36.101.
    band : s32 - Frequency Band.
    tauTriggered : s32 - Information if User Equipment is registered on evaluated cell. If not, Tracking Area Update will be triggered. See TRM2M_TXEVAL_TAU.
    ceLevel : s32 - CE Level estimation. Higher CE Level means more repetitions.
    txPower : s32 - Estimated tx power in [dBm].
    txRepetitions : s32 - Estimated tx repetitions.
    rxRepetitions : s32 - Estimated rx repetitions.
    downlinkPathloss : s32 - Reduction in power density in [dB].
    TRM2M_TXEVAL_TAU: s32

    Information if Tracking Area Update would be triggered on evaluated connection.

    RM2M_TXEVAL_TAU_TRIGGERED = 0 - Initial state
    RM2M_TXEVAL_TAU_NOT_TRIGGERED = 1 - Newly produced device is in stock
    RM2M_TXEVAL_TAU_TRIG_UNKNOWN = 255 - Valid contract
    TRM2M_TXEVAL_ENERGY_EST: s32

    Energy estimation of evaluated connection.

    RM2M_TXEVAL_ENERGY_EST_BAD = 0
    RM2M_TXEVAL_ENERGY_EST_POOR = 1
    RM2M_TXEVAL_ENERGY_EST_NORMAL = 2
    RM2M_TXEVAL_ENERGY_EST_GOOD = 3
    RM2M_TXEVAL_ENERGY_EST_BEST = 4
    TRM2M_TXEVAL_RRCSTATE: s32

    RRC state of evaluated connection.

    RM2M_TXEVAL_RRCSTATE_IDLE = 0
    RM2M_TXEVAL_RRCSTATE_CONNECTED = 1

    CONFIG CONTAINERS

    configX_basics:

    rapidM2M provides up to 10 CONFIG containers for information exchange between DEVICE and BACKEND.

    Typical content:

  • Device status
  • Device setup

    • Each container may be marked either for

  • UPward (sourced by device) or
  • DOWNward (sourced by backend)

    • information flow.

    Optionally containers may be marked volatile (configx_volatile).

    configx_volatile:

    By default, each config update at the device (DLO - DDE_xxx_write(), rM2M_CfgWrite()) is immediately persisted to FLASH memory.

    High update frequencies are power consuming and may have a negative impact on the FLASH memory's lifetime!

    Volatile containers avoid this adverse situation and allow a

  • high update frequency, at a
  • low persistance rate to protect the FLASH memory.

    • A volatile container holds it's data changes in RAM instead of FLASH memory.

    To enable volatility define the container like that:

    #config0 status dlo-volatile
    Volatile containers loose their data upon any reboot of the device. Therefore DDE_xxx_read() / onUplinkRestore_xxx() functions are disabled.

    To support recovery upon boot nevertheless and keep DDE_xxx_read() / onUplinkRestore_xxx() functions:

    #config0 status dlo-volatile=lazy
    // upon certain important changes or just from time to time call DDE_xxx_persist(); // to do lazy on-demand-persistance at a lower frequency than writing.
    Tutorial Volatile #config containers
    Legacy implementations may use rM2M_CfgInit( RM2M_CFG_VOLATILE) and rM2M_CfgFlush() instead.
    rM2M_CfgInit(cfg, flags)

    Sets the configuration for a configuration memory block. Calling the function is only necessary if one of the configuration flags should be set.

    cfg : TrM2M_Cfg - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.
    flags : s32 - Configuration flags to be set/deleted
    Bit0: Type of storage
    0(default) - stored in FLASH in non-volatile manner
    RM2M_CFG_VOLATILE - saved in RAM in volatile manner
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror

    Additional explanation on the type of storage:

    If Bit 0 was not set (default), the non-volatile storage of the configuration memory block in the FLASH is initiated when the rM2M_CfgWrite() function is called up.

    If Bit0 was set (Bit0 = RM2M_CFG_VOLATILE), the configuration memory block is saved in the RAM in a volatile manner when the rM2M_CfgWrite() function is called. This option is recommended if the data in the configuration memory block changes frequently as this will reduce the number of flash write cycles. The rM2M_CfgFlush() function must be called up so that the configuration memory block is saved in a non-volatile manner in the FLASH.

    rM2M_CfgWrite(cfg, pos, const data{}, size)

    Saves the transferred data block at the specified position in a configuration memory block. Note that the configuration memory block is either saved in the RAM in a volatile manner (Bit0 = RM2M_CFG_VOLATILE) or in the FLASH in a non-volatile manner (Bit0 = 0, default) depending on the type of storage selected via the rM2M_CfgInit() function. The function is also passed which of the 10 available memory blocks in the internal flash memory should be used. Use the rM2M_Pack(), rM2M_SetPacked() or rM2M_SetPackedB() functions to generate the data block that should be saved. The time stamp is updated, so that the configuration memory block is automatically synchronised with the rapidM2M Portal server during the next connection.

    cfg : TrM2M_Cfg - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.
    pos : s32 - Byte offset within the configuration memory block to determine the position where the data should be written.
    data{} : u8 - Array that contains the data that should be written in the configuration memory block.
    size : s32 - Number of bytes that should be written in the configuration memory block
    returns : Terror
    > 0 - Current size of the configuration memory block if successful
    ERROR_MEM - If enough temporary memory (RAM) is not currently available. (can occur if "RAM in a volatile manner" is selected as the type of storage for several configuration memory blocks)
    <OK - If another error occurs, see Terror
    rM2M_CfgFlush(cfg)

    Saves the configuration memory block for which the number was transferred in the FLASH in a non-volatile manner. Calling the function is only necessary if "volatile in RAM (Bit0 = RM2M_CFG_VOLATILE)" was selected as the type of storage for the relevant configuration memory block via the rM2M_CfgInit() function.

    cfg : TrM2M_Cfg - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_CfgRead(cfg, pos, data{}, size, &stamp=0, &stamp256=0)

    Reads a data block from the specified position in a configuration memory block. The function is also informed which of the 10 available memory blocks in the internal flash memory should be read. Use the rM2M_Pack(), rM2M_GetPacked() or rM2M_GetPackedB() functions to unpack the read data.

    cfg : TrM2M_Cfg - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.
    pos : s32 - Byte offset within the configuration memory block to determine the position where the data should be read.
    data{} : u8 - Array to store the data to be read
    size : s32 - Number of bytes that should be read from the configuration memory block
    stamp : s32 - Timestamp of the configuration object, seconds elapsed since 31st Dec 1999.
    stamp256 : s32 - Timestamp of the configuration object, 1/256s.
    returns : Terror
    >0 - Number of bytes actually read. This may be less or equal to the requested number of bytes.
    ERROR_MEM - If enough temporary memory (RAM) is not currently available. (can occur if "RAM in a volatile manner" is selected as the type of storage for several configuration memory blocks)
    <OK - If another error occurs, see Terror
    rM2M_CfgDelete(cfg)

    Deletes all of the data of the transferred configuration memory block.

    cfg : TrM2M_Cfg - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.
    returns : Terror
    OK - If successful
    ERROR_MEM - If enough temporary memory (RAM) is not currently available. (can occur if "RAM in a volatile manner" is selected as the type of storage for several configuration memory blocks)
    <OK - If another error occurs, see Terror
    TCfgOnChg_Callback(
    public func( cfg);
    Function to be provided by the device logic developer, that is called up if one of the configuration memory blocks has changed (registered with rM2M_CfgOnChg() ).
    cfg : TrM2M_Cfg - Number of the changed configuration memory block starting with 0 for the first memory block
    rM2M_CfgOnChg(funcidx)

    Specifies the function that should be called if one of the configuration memory blocks has changed (i.e. has been updated by the server).

    The callback does not trigger upon local (device-side) changes of a config.

    funcidx : s32 - Index of the public function that should be called up if the configuration has changed.

    Type of the function (see TCfgOnChg_Callback):
    public func( cfg);
    returns : Terror
    OK - If successful
    ERROR - If no valid index of a public function was transferred
    <OK - If another error occurs, see Terror
    TrM2M_Cfg

    0..9 - Number of the configuration memory block starting with 0 for the first memory block. The device comprises 10 independent memory blocks.

    HISTDATA CONTAINERS

    histdataX_basics:

    rapidM2M provides up to 10 HISTDATA containers for exchange of timeseries data between DEVICE and BACKEND.

    Typical content:

  • Measurement data
  • Event data

    • HISTDATA containers support UPward (sourced by device) direction, only.

    All HISTDATA containers are interlaced into a single timeseries buffer for transmission. Therefore each record must

  • be prefixed with a split tag value
  • have a stamp which is at least 1 tick (stamp40) younger than the previous one (if not, the rM2M_RecData will readjust the stamp accordingly)

    • Due to the complexity of the split tag concept it may be ofreasonable advantage to use the rapidM2M Studio's DDE libraries instead.
    rM2M_LiveData(const data{}, len)

    Transmits a data record as live data to the server. Calling this function is only permissible if the device is in "online" mode and an active connection to the server is established. Use the rM2M_Pack(), rM2M_SetPacked() or rM2M_SetPackedB() functions to generate the data area.

    data{} : u8 - Array that contains the live data to be transferred
    len : s32 - Number of bytes to be transferred (max. 1024 Byte )
    returns : Terror
    OK - If successful
    ERROR - If an error occurs (e.g. the server does not support receipt of live data.)
    rM2M_RecData(timestamp, const data{}, len)

    Saves a data record in the internal flash memory. Use the rM2M_Pack(), rM2M_SetPacked() or rM2M_SetPackedB() functions to generate the data area.

    timestamp : stamp32 - Time stamp that should be used for the recording
    0 - The current system time is used as the time stamp.
    >0 - The transferred time stamp is used.
    (The time stamp must be specified in seconds since 31.12.1999)
    data{} : u8 - Array that contains the data to be saved
    len : s32 - Number of bytes to be saved (max. 1024 Byte )
    returns : Terror
    OK - If successful
    -2 - If data storage is not currently possible as the internal memory is being reorganised. The data must be temporarily saved in the device logic and stored again at a later date.
    ERROR - If one of the following errors occurs
  • Memory area (data{}, len) is invalid
  • More than 10 calls during one script run
  • Number of bytes to be saved > 1024 Byte
  • FLASH write process not successful
  • The transfer parameter "timestamp" is more than 5 minutes in the future
    • <OK - If another error occurs, see Terror
    TReadData_Callback(
    public func( const data[], len, timestamp, timestamp256););
    Function to be provided by the device logic developer, that is called up, once a data record has been read (using the function rM2M_ReadData() ) from the internal flash memory.
    The parameter "timestamp256" has only been added in later firmware versions. The number of arguments transferred from the firmware to the callback function should thus be checked via the function "numargs()"
    Example:
    #callback readdata_callback(const data{}, len, timestamp, timestamp256) { if(numargs() >= 4) { // parameter timestamp256 is available ... } }
    data[] - Array that contains the data of the read data record
    len : s32 - Length of the data area of the read data record in bytes (max. 1024 Byte )
    timestamp : stamp32 - Time stamp of the data record (in UTC)
    timestamp256 : s32 - Fraction of the next started sec. (Resolution 1/256 sec.)
    rM2M_ReadData(recidx, funcidx)

    Reads out a data record saved in the internal flash and then calls up the function for which the index was transferred.

    recidx : s32 - Index of the data record to be read (-1 = last/current data record, -2 = penultimate data record, .... )
    funcidx : s32 - Index of the public function that should be called once the data record has been read from the internal flash memory.

    Type of the function (see TReadData_Callback):
    public func( const data[], len, timestamp, timestamp256);
    returns : Terror
    OK - If the read process has been started
    ERROR - If an error occurs
    // best to use this function at early boot phase (before starting rest of the app) runApp(){ ...run your appcode here... } #callback onRecData( const data[], len, stamp) { #log( "youngest histdata= %s", stampToISOString( stamp)); runApp(); } main() { catch( rM2M_ReadData( -1, onRecData)); }

    ENCODING

    rM2M_SetPackedB(data{}, pos, const block{}, size)

    Writes the transferred data block to the specified position in an array.

    data{} : u8 - Array that should be used as a data area for a data record or a configuration
    pos : s32 - Byte offset within the array to determine the position where the data block should be written
    block{} : u8 - Data block that should be written in the array
    size : s32 - Number of bytes to be written from the data block to the array
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_GetPackedB(const data{}, pos, block{}, size)

    Reads a data block that is located at the specified position in an array.

    data{} : u8 - Array that should be used as a data area for a data record or a configuration
    pos : s32 - Byte offset within the array to determine the position from which the data should be read
    block{} : u8 - Array to store the data to be read
    size : s32 - Number of bytes that should be read
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TrM2M_PackType:

    Configuration flags for the rM2M_Pack() function

    RM2M_PACK_GET = 0b00000001 - Value should be read (get packed)
    RM2M_PACK_BE = 0b00000010 - Use "Big endian" format
    RM2M_PACK_U8 = 0b00010000 - 8-bit unsigned
    RM2M_PACK_S8 = 0b10010000 - 8-bit signed
    RM2M_PACK_U16 = 0b00100000 - 16-bit unsigned
    RM2M_PACK_S16 = 0b10100000 - 16-bit signed
    RM2M_PACK_U32 = 0b01000000 - 32-bit unsigned
    RM2M_PACK_S32 = 0b11000000 - 32-bit signed
    RM2M_PACK_F32 = 0b01000000 - 32-bit float
    rM2M_Pack(const data{}, pos, &{Float,Fixed,_}:value, type)

    Function to access packed data. If the Bit0 (RM2M_PACK_GET) of the "type" parameter was set, the function returns the value that is located at the specified position in the array. Otherwise the function writes the transferred value to the specified position in the array.

    data{} : u8 - Array with the packed content
    Set packed: Array to which the value should be written
    Get packed: Array from which the value should be read
    pos : s32 - Byte offset within the array
    Set packed: Position to which the value should be written
    Get packed: Position from which the value should be read
    value : f32|RM2M_PACK_S32
    Set packed: Value that should be written in the array
    Get packed: Variable to store the data to be read
    type : TrM2M_PackType - Configuration flags for the function
    Bit0: Select "Set packed" / "Get packed"
    0 - Value should be written
    1 - Value should be read
    Bit1: Byte order
    0 - "Little endian" format
    1 - "Big endian" format
    Bit2...3: reserved for extensions
    Bit4...7: Data type
    1 - 8-bit unsigned
    2 - 16-bit unsigned
    4 - 32-bit unsigned / 32-bit float
    9 - 8-bit signed
    10 - 16-bit signed
    12 - 32-bit signed
    You can also use the predefined constants for this parameter, see TrM2M_PackType.
    The constants can also be combined using the "or" link.
    Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    swapchars(c)

    Swaps the order of the bytes

    c : s32 - Value for which the bytes should be swapped over
    returns : s32 - Value for which the bytes in parameter "c" are swapped over (the lowest byte becomes the highest byte)

    REGISTRY

    rM2M_RegInit(reg, flags, data{}, len=sizeof data)

    Initialises one of the optional registration memory blocks stored in the RAM. Calling up the function is only necessary for the registration memory blocks listed in the explanation of the "reg" parameter.

    reg : TrM2M_RegId - Registration memory block index
    The following registration memory blocks require an initialisation:
    RM2M_REG_APP_STATE - Application-specific, volatile data (e.g. current device status)
    flags : s32 - Configuration flags to be set/deleted
    Bit0: Type of storage
    0 - Invalid, currently not supported
    RM2M_REG_VOLATILE = 0b00000001 - Saved in RAM in volatile manner
    data{} : u8 - Array to store the registration memory block
    len : s32 - Size (in cells) of the transferred array to store the registration memory block (max. 1kB ) - OPTIONAL
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegGetString(reg, const name[], string[], len=sizeof string)

    Reads a character string from a registration memory block.

    reg : TrM2M_RegId - Index of the registration memory block
    RM2M_REG_APP_STATE requires rM2M_RegInit() before.
    name : astr - Name of the entry
    str : astr - Array to store the string to be read
    (Extended JSON string format, see rM2M_RegSetString() for details)
    len : s32 - Size (in cells) of the transferred array to store the string to be read - OPTIONAL
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    RM2M_REG_ERROR_NOTFOUND - If the specified entry does not exist
    RM2M_REG_ERROR_ISNULL - If the value of the specified entry is set to "null"
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegGetValue(reg, const name[], &{Float,Fixed,_}:value, tag=tagof value)

    Reads a value from a registration memory block.

    reg : TrM2M_RegId - Index of the registration memory block
    RM2M_REG_APP_STATE requires rM2M_RegInit() before.
    name : astr - Name of the entry
    value : s32|f32 - Variable to store the value to be read
    tag - The integer and floating-point conversion are differentiated by the "tag" of the variables. - OPTIONAL
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    RM2M_REG_ERROR_NOTFOUND - If the specified entry does not exist
    RM2M_REG_ERROR_ISNULL - If the value of the specified entry is set to "null"
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegSetString(reg, const name[], const string[])

    Writes a character string into a registration memory block.

    This function accepts even characters which are fobidden according to JSON standard, such as \t, \n,...Due to this, Javascript's JSON.parse() will fail with error messages. Use JSON5 instead to decode such extended strings.
    reg : TrM2M_RegId - Index of the registration memory block
    name : astr - Name of the entry
    If an entry with this name already exists, the existing character string is replaced by the transferred character string. Otherwise a new entry is created.
    string : astr - Array that contains the string to be written
    (Extended JSON string format is supported by JSON5)
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegSetValue(reg, const name[], {Float,Fixed,_}:value, tag=tagof value)

    Writes a value into a registration memory block.

    reg : TrM2M_RegId - Index of the registration memory block
    name : astr - Name of the entry
    If an entry with this name already exists, the existing value is replaced by the transferred value. Otherwise a new entry is created.
    value : s32|f32 - Value to be written
    tag - The integer and floating-point conversion are differentiated by the "tag" of the value. - OPTIONAL
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegDelValue(reg, const name[])

    Searches for an entry based on its name and sets the value of this entry (regardless of whether it is a string or value) to "null".

    reg : TrM2M_RegId - Index of the registration memory block
    name : astr - Name of the entry for which the value should be set to "null"
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    <OK - If another error occurs, see TrM2M_RegError
    rM2M_RegDelKey(reg, const name[])

    Searches for an entry based on its name and deletes the entry from the registration memory block.

    reg : TrM2M_RegId - Index of the registration memory block
    name : astr - Name of the entry that should be deleted from the registration memory block
    returns : TrM2M_RegError
    OK - If successful
    ERROR - If an unspecified errors occurs
    <OK - If another error occurs, see TrM2M_RegError
    TRegOnChg_Callback(
    public func( reg);
    Function to be provided by the device logic developer, that is called up if the registration has changed (registered with rM2M_RegOnChg() ).
    reg : TrM2M_RegId - Index of the registration memory block
    rM2M_RegOnChg(funcidx)

    Specifies the function that should be called up if one of the registration memory blocks has changed (i.e. has been updated by the server). The callback is not triggered upon local (device-side) changes of a registration memory.

    funcidx : s32 - Index of the public function that should be called up if the registration has changed.

    Type of the function (see TRegOnChg_Callback):
    public func( reg);
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TrM2M_RegId:

    Indices of the registration memory blocks

    that can be accessed via the rM2M_RegGetString(), rM2M_RegGetValue(), rM2M_RegSetString(), rM2M_RegSetValue(), rM2M_RegDelValue() and rM2M_RegDelKey() functions.
    System-specific data
    RM2M_REG_SYS_OTP = 0 - Written once as part of the production process (readonly by device logic).
    RM2M_REG_SYS_FLASH = 1 - Can be changed during operation (readonly by device logic).
    Application specific data
    RM2M_REG_APP_OTP = 2 - Recommendation: Write only once as part of the production process (readable and writeable by device logic).
    RM2M_REG_APP_FLASH = 3 - Can be changed during operation (readable and writeable by device logic).
    Application-specific, volatile data
    RM2M_REG_APP_STATE = 4 - Can be changed during operation (readable and writeable by device logic). Requires rM2M_RegInit() before.
    System-specific data
    RM2M_REG_SYS_INFO = 5 - Written once as part of the production process (readonly by device logic).
    Application specific data
    RM2M_REG_APP_INFO = 6 - Used to store some non volatile values from application (readable and writeable by device logic).
    Number of registration memory blocks
    RM2M_REG_NUM_REGS = 7
    TrM2M_RegError:

    Error codes for the registration memory block access operations

    OK = 0
    ERROR - same as with Terror
    RM2M_REG_ERROR_TOKENMEM = -101 - Not enough tokens were provided
    RM2M_REG_ERROR_INVAL = -102 - Invalid character inside JSON string
    RM2M_REG_ERROR_PART = -103 - The string is not a full JSON packet, more bytes expected
    RM2M_REG_ERROR_NOMEM = -200 - Memory allocation failed
    RM2M_REG_ERROR_NUMTOKENS = -201 - Not enough token available for this object/array size
    RM2M_REG_ERROR_PAIR = -202 - Found invalid pair (string : value)
    RM2M_REG_ERROR_NOTOKENS = -203 - Not enough tokens free for appending
    RM2M_REG_ERROR_NOTFOUND = -204 - Specified pair not found
    RM2M_REG_ERROR_TYPE = -205 - Token type mismatch
    RM2M_REG_ERROR_PARAM = -206 - Invalid parameters
    RM2M_REG_ERROR_SIZE = -207 - Size exceeds maximum allowed
    RM2M_REG_ERROR_INVALID = -208 - JSON structure invalid
    RM2M_REG_ERROR_ISNULL = -209 - Value is null

    POSITION

    rM2M_SetPos(Lat, Long, Elev, Qual, SatUsed)

    Saves the GPS position information in the device. A historical record is not maintained. This means that the current position information always overwrites the last known position. The information is transmitted to the rapidM2M Portal server and can, for example, be read out via the API.

    Lat : TrM2M_PosLat - Geographical latitude in degrees (resolution: 0.000001°)
    -90.000.000 - South pole 90° south
    0 - Equator
    +90.000.000 - North pole 90° north
    Long : TrM2M_PosLong - Geographical longitude in degrees (resolution: 0.000001°)
    -180.000.000 - 180° west
    0 - Zero meridian (Greenwich)
    +180.000.000 - 180° east
    Elev : TrM2M_PosAlt - Height above sea level in meters (Valid range: -999...+9999)
    Qual : TrM2M_NMEA_FIX - Quality indicator (GPS quality indicator)
    RM2M_NMEA_FIX_NOK - Invalid/no fix
    RM2M_NMEA_FIX_GPS - Non-differential GPS fix
    RM2M_NMEA_FIX_DGPS - Differential GPS fix
    RM2M_NMEA_FIX_PPS - Precise positioning service (PPS)
    RM2M_NMEA_FIX_RTK - Real time kinematic (RTK)
    RM2M_NMEA_FIX_FLOATRTK - Float real time kinematic
    RM2M_NMEA_FIX_EST - Estimated fix (dead reckoning, coupled navigation)
    RM2M_NMEA_FIX_MAN - Manual input mode
    RM2M_NMEA_FIX_SIM - Simulation mode
    SatUsed : s32 - Number of satellites used for the positioning (valid range: 0 ... 99)
    returns : Terror
    OK - If successful
    ERROR
    The parameters are checked against the specified range limits. The function returns "ERROR" if the limits are not adhered to.
    rM2M_DecodeNMEA(const sentence{}, data[], len=sizeof data)

    Decodes a transferred NMEA data record.

    sentence{} : astr - NMEA data record from a GPS receiver starting with the '$' character.
    The strings must be terminated ('\0') immediately after the checksum.
    data[] : s32 - Buffer (cell array) to store the decoded data

    [0] - Contains the GNSS device ID
    (in accordance with the "Talker ID" used with the NMEA 0183 standard)
    RM2M_NMEA_DEVICE_GP = 0x244750 - $GP (GPS)
    RM2M_NMEA_DEVICE_GL = 0x24474C - $GL (GLONASS)
    RM2M_NMEA_DEVICE_GA = 0x244741 - $GA (GALILEO)
    RM2M_NMEA_DEVICE_GN = 0x24474E - $GN (GENERIC GNSS)

    [1] - Contains the type of decoded NMEA data record
    RM2M_NMEA_RECORD_GGA = 0x474741 - GGA (global positioning system fix data)

    [2] ... [n] - Dependent on type of decoded NMEA data record

    For a type "RM2M_NMEA_RECORD_GGA" data record, the remaining structure is the same as the "TNMEA_GGA" structure.

    [2] - .Lat
    [3] - .Long
    [4] - .Alt
    [5] - .Qual
    [6] - .SatUsed
    [7] - .HDOP

    len : s32 - Size (in cells) of the buffer to store the decoded data – OPTIONAL
    returns : TrM2M_NMEA_ERR
    >0 - If successful (number of filled array elements, i.e. cells)
    <0 - If an error has occurred, see TrM2M_NMEA_ERR
    rM2M_SetPosNMEA(const Sentence{})

    Takes the GPS position information from the transferred NMEA data record and saves it in the device. A historical record is not maintained. This means that the current position information always overwrites the last known position. The information is transmitted to the rapidM2M Portal server and can, for example, be read out via the API.

    Sentence{} : astr - NMEA data record from a GPS receiver starting with the '$' character. The following data records are currently supported:
  • $GPGGA - location specification (fix information)
    • The strings must be terminated ('\0') immediately after the checksum.
    returns : TrM2M_NMEA_ERR
    OK - If successful
    <OK - If an error occurs, see TrM2M_NMEA_ERR
    rM2M_GetPos(&Lat, &Long, &Elev, &Qual=0, &SatUsed=0)

    Reads out the GPS position information saved to the device.

    Lat : TrM2M_PosLat - Variable to store the geographical latitude in degrees (resolution: 0.000001°)
    -90.000.000 - South pole 90° south
    0 - Equator
    +90.000.000 - North pole 90° north
    Long : TrM2M_PosLong - Variable to store the geographical longitude in degrees (resolution: 0.000001°)
    -180.000.000 - 180° west
    0 - Zero meridian (Greenwich)
    +180.000.000 - 180° east
    Elev : TrM2M_PosAlt - Variable to store the height above sea level in meters (Valid range: -999...+9999)
    Qual : TrM2M_NMEA_FIX - Variable to store the quality indicator (GPS quality indicator) – OPTIONAL
    RM2M_NMEA_FIX_NOK - Invalid/no fix
    RM2M_NMEA_FIX_GPS - Non-differential GPS fix
    RM2M_NMEA_FIX_DGPS - Differential GPS fix
    RM2M_NMEA_FIX_PPS - Precise positioning service (PPS)
    RM2M_NMEA_FIX_RTK - Real time kinematic (RTK)
    RM2M_NMEA_FIX_FLOATRTK - Float real time kinematic
    RM2M_NMEA_FIX_EST - Estimated fix (dead reckoning, coupled navigation)
    RM2M_NMEA_FIX_MAN - Manual input mode
    RM2M_NMEA_FIX_SIM - Simulation mode
    SatUsed : s32 - Variable to store the number of satellites used for positioning – OPTIONAL
    returns : Terror
    OK - If valid GPS position information is stored in the device
    <OK - If an error occurs, see Terror
    rM2M_PosUpdate(...)

    Makes it possible to transfer information about the GSM/UMTS/LTE cells and WiFi networks to the device. The position data is thus generated based on this information provided by the user. This function uses a variable list of parameters. The parameters to be passed depend on the purpose. The following procedure is recommended:

    1. Preparing a new position data record
      rM2M_PosUpdate(RM2M_POSUPDATE_TYPE_WIFI); // e.g. WiFi

      The internally saved list of cell/network information is discarded and a new one is prepared. The time stamp of this new list is set to the current time.

    2. Transferring the cell/network information entries to the system
      rM2M_PosUpdate(RM2M_POSUPDATE_TYPE_WIFI, sData[TrM2M_PosUpdateWiFi], sizeof sData); // e.g. WiFi

      The transferred cell/network information entry is entered in the list that was created during step 1. The ".type" and ".stamp" entries in the "TrM2M_PosUpdatexxx" structure are ignored. A maximum of 20 cell/network information entries can be entered in the list.

      A suitable type of cell/network information for the "TrM2M_PosUpdatexxx" structure transferred in the "sData" data buffer must be specified for the "type".
    3. Completing position data record by transferring a "Dummy" cell/network information entry with a length of 0.
      rM2M_PosUpdate(RM2M_POSUPDATE_TYPE_WIFI, [0], 0); // e.g. WiFi

      The list of cell/network information entries is sorted (in descending order based on the reception level) and the time stamp is updated. The time stamp is used for the synchronisation of the position data with the server. If the device is currently in online mode, the position data is immediately transferred to the server. If the cell/network information entries are read out again via the rM2M_EnumPosUpdate() function, the time stamp generated during step 3 is entered in the "TrM2M_PosUpdatexxx" structure.

    type : RM2M_POSUPDATE_TYPE_xxx - Type of cell/network information transferred to the system
    sData - Cell/network information entry that should be transferred to the system. The data structure is dependent on the selected type ("type" parameter).
    e.g. "TrM2M_PosUpdateWiFi" for type "RM2M_POSUPDATE_TYPE_WIFI"
    len : s32
  • Size (in cells) of the cell/network information entry that was copied into the "sData" data buffer
  • Zero to indicate that no further cell/network information entries, that should be taken into consideration for the current position data record, will be transferred to the system.
    • returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED
    ERROR-1 - If temporarily not possible (e.g. internal position update active)
    <OK - If another error occurs, see Terror
    rM2M_EnumPosUpdate(...)

    lists the information saved in the device about the GSM/UMTS/LTE cells and WiFi networks in the receiving range. This function uses a variable list of parameters. The parameters to be passed depend on the purpose. The following procedure is recommended:

    1. Reading of the number of available cell/network information entries
      new nEnum; rM2M_EnumPosUpdate( nEnum);
    2. Determination of the particular type of the cell/network information entries
      new type; new idxEnum = 0; for(idxEnum=0 ; idxEnum < nEnum ; idxEnum++) rM2M_EnumPosUpdate(idxEnum, type);
    3. Reading of cell/network information entries based on the types determined previously
      (in the following example only those that contain information about a GSM cell)
      new sGSMPos[TrM2M_PosUpdateGSM]; if(type == RM2M_POSUPDATE_TYPE_GSM) rM2M_EnumPosUpdate(idxEnum, sGSMPos, sizeof sGSMPos);
    nEnum : s32 - Variable to store the number of available cell/network information entries
    idxEnum : s32 - Index of the cell/network information entry whose type should be determined or that should be read by the system.

    Either the "type" parameter or the two "buf" and "len" parameters are required in addition depending on the desired action.

    type : RM2M_POSUPDATE_TYPE_xxx - Variable to store the type of a cell/network information entry
    buf : TrM2M_PosUpdatexxx - Buffer to store a cell/network information entry

    The structure of the buffer depends on the cell/network information entry to be read.

    len : s32 - Size (in cells) of the structure to store a cell/network information entry
    returns : Terror
    OK - If successful
    ERROR - If an error occurs, see Terror

    // read the number of available entries new nEnum; rM2M_EnumPosUpdate( nEnum); for(new idxEnum=0 ; idxEnum < nEnum ; idxEnum++) { // read type information of an entry new type; rM2M_EnumPosUpdate( idxEnum, type); // read data based on the detected type new sGSMPos[TrM2M_PosUpdateGSM]; if(type == RM2M_POSUPDATE_TYPE_GSM) rM2M_EnumPosUpdate( idxEnum, sGSMPos, sizeof sGSMPos); }
    rM2M_GetGSMPos(posidx, pos[TrM2M_GSMPos]=0)

    Returns the number of GSM/UMTS/LTE cells for which valid information is saved in the device (posidx < 0) or reads out the information saved in the device about a GSM/UMTS/LTE cell in the receiving range (posidx >= 0).

    Use the rM2M_EnumPosUpdate() function in order to get information on WiFi networks in the receiving range or more specific information on UMTS and/or LTE cells.
    posidx : s32 - Selection of the information returned by the function
    <0 - Read the number of GSM/UMTS/LTE cells for which valid information is saved in the device
    >=0 - Number of the GSM/UMTS/LTE cell information block that should be read
    pos : TrM2M_GSMPos
    posidx <0 - Not required
    posidx >=0 - Structure for storing the information about a GSM/UMTS/LTE cell in the receiving range, see TrM2M_GSMPos
    returns : Terror
    posidx <0 - Number of GSM/UMTS/LTE cells for which valid information is saved in the device (max. 10)
    posidx >=0
  • OK - If the desired cell information block contains valid data of a GSM cell
  • OK+1 - If the desired cell information block contains valid data of a UMTS cell
  • OK+2 - If the desired cell information block contains valid data of a LTE cell
  • ERROR - If no position information available
    • TrM2M_GSMPos:

    Information about a GSM/UMTS/LTE cell in the receiving range

    mcc : s32 - MCC (Mobile Country Code) of the GSM cell
    mnc : s32 - MNC (Mobile Network Code) of the GSM cell
    lac : s32 - LAC (Location Area Code) of the GSM cell
    cellid : s32 - Cell ID of the GSM cell
    rssi : s32 - Detected GSM level [dBm] for the GSM cell
    ta : s32 - TA (Timing Advance) of the GSM cell (currently always 0)
    TrM2M_PosLat

    Geographical latitude in degrees (resolution: 0.000001°)

    -90.000.000 = South pole 90° S
    0 = Equator
    +90.000.000 = North pole 90° N
    TrM2M_PosLong

    Geographical longitude in degrees (resolution: 0.000001°)

    -180.000.000 = 180° West
    0 = Zero meridian
    +180.000.000 = 180° East
    TrM2M_PosAlt

    Height above sea level in meters

    TrM2M_NMEA_FIX: s32

    NMEA Quality indicator

    RM2M_NMEA_FIX_NOK = 0 - Invalid/no fix
    RM2M_NMEA_FIX_GPS = 1 - Non-differential GPS fix
    RM2M_NMEA_FIX_DGPS = 2 - Differential GPS fix
    RM2M_NMEA_FIX_PPS = 3 - Precise positioning service (PPS)
    RM2M_NMEA_FIX_RTK = 4 - Real time kinematic (RTK)
    RM2M_NMEA_FIX_FLOATRTK = 5 - Float real time kinematic
    RM2M_NMEA_FIX_EST = 6 - Estimated fix (dead reckoning, coupled navigation)
    RM2M_NMEA_FIX_MAN = 7 - Manual input mode
    RM2M_NMEA_FIX_SIM = 8 - Simulation mode
    TrM2M_NMEA_ERR:

    Error codes of the function rM2M_SetPosNMEA()

    RM2M_NMEA_ERR_DATATYPE = -2 - Datatype (e.g. $GGSA) is not supported
    RM2M_NMEA_ERR_SENTENCE = -3 - Sentence is not valid (e.g. checksum error)
    RM2M_NMEA_ERR_LATITUDE = -4 - Geographical latitude invalid
    RM2M_NMEA_ERR_LONGITUDE = -5 - Geographical longitude invalid
    RM2M_NMEA_ERR_ALTITUDE = -6 - Altitude above sea level invalid
    RM2M_NMEA_ERR_SAT_USED = -7 - Number of satellites used invalid
    RM2M_NMEA_ERR_QUAL = -8 - GPS quality indication not supported
    TNMEA_GGA:

    Information (position, height above sea level and accuracy) extracted from a GGA data record.

    Lat : TrM2M_PosLat - Geographical latitude in degrees (resolution: 0.000001°)
    Long : TrM2M_PosLong - Geographical longitude in degrees (resolution: 0.000001°)
    Alt : TrM2M_PosAlt - Height above sea level in meters
    Qual : TrM2M_NMEA_FIX - NMEA Quality indicator
    SatUsed : s32 - Number of satellites used for the positioning
    HDOP : s32 - Relative accuracy of the horizontal position [0.01]
    RM2M_POSUPDATE_TYPE_xxx:

    List of the supported types of cell/network information entries

    Possible types of cell/network information entries that can be read from the system via the function rM2M_EnumPosUpdate().
    RM2M_POSUPDATE_TYPE_ERR = 0 - Invalid entry
    RM2M_POSUPDATE_TYPE_GSM = 1 - Information about a GSM cell
    RM2M_POSUPDATE_TYPE_UMTS = 2 - Information about a UMTS cell
    RM2M_POSUPDATE_TYPE_LTE = 3 - Information about an LTE cell
    RM2M_POSUPDATE_TYPE_WIFI = 4 - Information about a WiFi network
    TrM2M_PosUpdateGSM:

    Information about a GSM cell in the receiving range

    type : RM2M_POSUPDATE_TYPE_xxx - Specifies the type of the entry (RM2M_POSUPDATE_TYPE_GSM)
    stamp : s32 - Time when data was recorded
    mcc : s32 - MCC (Mobile Country Code) of the GSM cell
    mnc : s32 - MNC (Mobile Network Code) of the GSM cell
    lac : s32 - LAC (Location Area Code) of the GSM cell
    cid : s32 - Cell ID of the GSM cell
    rssi : s32 - Detected GSM level [dBm] for the GSM cell
    ta : s32 - TA (Timing Advance) of the GSM cell (currently always 0
    TrM2M_PosUpdateUMTS:

    Information about a UMTS cell in the receiving range

    type : RM2M_POSUPDATE_TYPE_xxx - Specifies the type of the entry (RM2M_POSUPDATE_TYPE_UMTS)
    stamp : s32 - Time when data was recorded
    mcc : s32 - MCC (Mobile Country Code) of the UMTS cell
    mnc : s32 - MNC (Mobile Network Code) of the UMTS cell
    lac : s32 - LAC (Location Area Code) of the UMTS cell
    cid : s32 - UTRAN cell ID
    rscp : s32 - Received Signal Code Power [dBm]
    pscr : s32 - Primary Scrambling Code
    TrM2M_PosUpdateLTE:

    Information about an LTE cell in the receiving range

    type : RM2M_POSUPDATE_TYPE_xxx - Specifies the type of the entry (RM2M_POSUPDATE_TYPE_LTE)
    stamp : s32 - Time when data was recorded
    mcc : s32 - MCC (Mobile Country Code) of the LTE cell
    mnc : s32 - MNC (Mobile Network Code) of the LTE cell
    lac : s32 - LAC (Location Area Code) of the LTE cell
    cid : s32 - E-UTRAN cell ID
    rsrp : s32 - Reference Signal Received Power [dBm]
    TrM2M_PosUpdateWiFi:

    Information about a WiFi network in the receiving range

    type : RM2M_POSUPDATE_TYPE_xxx - Specifies the type of the entry (RM2M_POSUPDATE_TYPE_WIFI)
    stamp : s32 - Time when data was recorded
    ch : u8 - WiFi RF channel (1-14 in 2.4 GHz frequency range), data type: u8
    rssi : s8 - WiFi RSSI Level [dBm], data type: s8
    bssid{6} : u8 - Basic Service Set Identification (e.g. MAC address of the access point)
    ssid{32+1} : u8 - Service Set Identifier of the WiFi network

    MATH

    min(value1, value2)

    Supplies the smaller of the two transferred values

    value1 : s32 - First of the two values of which the smaller one is to be determined
    value2 : s32 - Second of the two values of which the smaller one is to be determined
    returns : s32 - The smaller of the two transferred values
    max(value1, value2)

    Supplies the larger of the two transferred values

    value1 : s32 - First of the two values of which the larger one is to be determined
    value2 : s32 - Second of the two values of which the larger one is to be determined
    returns : s32 - The larger of the two transferred values
    clamp(value, min=cellmin, max=cellmax)

    Checks whether the transferred value is between "min" and "max" (cut-off value at the min/max limits)

    value : s32 - Value that is to be checked
    min : s32 - Lower limit
    max : s32 - Upper limit
    returns : s32
    value - If the value is between "min" and "max"
    min - If the value is less than "min"
    max - If the value is greater than "max"
    wrap
    wrap(value, min=cellmin, max=cellmax)

    Checks whether the transferred value is between "min" and "max" (wrap around value at the min/max limits)

    value : s32 - Value that is to be checked
    min : s32 - Lower limit
    max : s32 - Upper limit
    returns : s32
    value - If the value is between "min" and "max"
    min - If the value is greater than "max"
    max - If the value is less than "min"
    clamp
    M_E - 2.7182818284590452354

    e

    M_LOG2E - 1.4426950408889634074

    log_2 e

    M_LOG10E - 0.43429448190325182765

    log_10 e

    M_LN2 - 0.69314718055994530942

    log_e 2

    M_LN10 - 2.30258509299404568402

    log_e 10

    M_PI - 3.14159265358979323846

    pi

    M_PI_2 - 1.57079632679489661923

    pi/2

    M_PI_4 - 0.78539816339744830962

    pi/4

    M_1_PI - 0.31830988618379067154

    1/pi

    M_2_PI - 0.63661977236758134308

    2/pi

    M_2_SQRTPI - 1.12837916709551257390

    2/sqrt(pi)

    M_SQRT2 - 1.41421356237309504880

    sqrt(2)

    M_SQRT1_2 - 0.70710678118654752440

    1/sqrt(2)

    fround(Float:x)

    Commercially rounds the transferred float

    x : f32 - Float that should be rounded
    returns : s32 - Commercially rounded integral value
    Float:sin(Float:x)

    Sine of x

    Float:cos(Float:x)

    Cosine of x

    Float:tan(Float:x)

    Tangent of x

    Float:asin(Float:x)

    Arcsine(x) in the range [-π/2, π/2], x element of [-1, 1]

    Float:acos(Float:x)

    Arccosine(x) in the range [0, π], x element of [-1, 1]

    Float:atan(Float:x)

    Arctangent(x) in the range [-π/2, π/2]

    Float:atan2(Float:y, Float:x)

    Arctangent(y/x) in the range [-π, π]

    Float:sinh(Float:x)

    Hyperbolic sine of x

    Float:cosh(Float:x)

    Hyperbolic cosine of x

    Float:tanh(Float:x)

    Hyperbolic tangent of x

    Float:exp(Float:x)

    Exponential function ex

    Float:log(Float:x)

    Natural logarithm ln(x), x > 0

    Float:log10(Float:x)

    Logarithm as the basis 10

    log10(x), x > 0
    Float:pow(Float:x, Float:y)
    xy. An argument error has occurred if x = 0 and y <= 0, or if x < 0 and y is not a whole number.
    Float:sqrt(Float:x)

    Square root x, x >= 0

    Float:ceil(Float:x)

    Smallest whole number that is not smaller than x

    Float:floor(Float:x)

    Largest whole number that is not larger than x

    abs(n)

    Returns absolute value | n |

    n : s32 - Value for which the absolute value is to be determined
    returns : s32 - Absolute (positive) value
    Float:fabs(Float:x)

    Absolute value | x |

    Float:ldexp(Float:x, n)
    x*2n
    Float:frexp(Float:x, &n)

    Breaks down x into a normalised mantissa in the range [1/2, 1] that is supplied as the result, and a potency of 2 that is filed in n. If x is zero, both parts of the result are zero.

    Float:modf(Float:x, &Float:ip)

    Breaks down x into an integral and residual part that both have the same prefix as x. The integral part is filed in ip, while the residual part is the result.

    Float:fmod(Float:x, Float:y)

    Residual floating point of x/y with the same prefix as x. The result is dependent on the implementation, if y is zero.

    isnan(Float:x):s32

    Returns a value that is not equal to zero, if x is not a number

    rand()

    Returns a random number from the "32-Bit signed Integer" value range. However, value "-1" (ERROR) is reserved for returning an error.

    returns : s32
  • Random number from the "32-Bit signed Integer" value range (S32_MIN to S32_MAX)
  • ERROR if no random number generator is available

    • S64

    s64:
    The script(DLO) natively supports s32 (a "cell") only. Therefore s64 is implemented as binary buffer u8{8}.
    new s64_value{8}
    s64_set(val_s64, val)

    Transmits the content of a standard variable of the script language (32 bit signed integer) into an array which is designed for storing a 64 bit signed integer value.

    val_s64 : u8{8} - Array for storing a 64 bit signed integer value
    val : s32 - Variable of which the content should be transmitted into a 64 bit signed integer value
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_get(val_s64, &val)

    Transmits a 64 bit signed integer value into a standard variable of the script language

    The standard variables of the script language are designed for storing only 32 bit signed integer values. If the value saved in the array exceeds the 32 bit signed integer values margin, the transmitted value in "val" is invalid as the top 4 bytes are cut off. It is recommended to check if the 32 bit signed integer values margin has been exceeded before reading out the data using the "s64_cmp()" function.
    val_s64 : u8{8} - Array containing the 64 bit signed integer value
    val : s32 - Variable for storing the value to be read
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_add(term1, term2, sum)

    Sums up two 64 bit signed integer values (sum = term1 + term2)

    term1 : u8{8} - Array containing a value to be summed up
    term2 : u8{8} - Array containing a value to be summed up
    sum : u8{8} - Array for storing the result of the addition
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_sub(minuend, subtrahend, difference)

    Subtracts a 64 bit signed integer value from another one (difference = minuend - subtrahend)

    minuend : u8{8} - Array containing the value from which should be subtracted
    subtrahend : u8{8} - Array containing the value which should be subtracted
    difference : u8{8} - Array for storing the result of the subraction
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_mul(multiplier, multiplicand, product)

    Multiplies two 64 bit signed integer values (product = multiplier * multiplicand )

    multiplier : u8{8} - Array containing a value to be multiplied
    multiplicand : u8{8} - Array containing a value to be multiplied
    product : u8{8} - Array for storing the result of the multiplication
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_div(dividend, divisor, quotient)

    Divides a 64 bit signed integer value by another one (quotient = dividend / divisor)

    dividend : u8{8} - Array containing the value to be divided
    divisor : u8{8} - Array containing the value to divide
    quotient : s64
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_mod(dividend, divisor, reminder)

    Determines the reminder of the division of 64 bit signed integer values (reminder = dividend % divisor )

    dividend : u8{8} - Array containing the value to be devided
    divisor : u8{8} - Array containing the value to devide
    reminder : u8{8} - Array for storing the reminder remaining in the integer division
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_lshift(val, bits)

    Shifts the 64 bit signed integer value contained in the array 'val' 'bits' number of bits to the left (val <<= bits). The freed up bits are filled up with 0. This is an arithmetic shift, i.e. the leading sign is retained.

    val : u8{8} - Array containing the value
    bits : s32 - Number of bits that the value should be shifted to the left
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_rshift(val, bits)

    Shifts the 64 bit signed integer value contained in the array 'val' 'bits' number of bits to the right (val >>= bits). The freed up bits are filled up with 0. This is an arithmetic shift, i.e. the leading sign is retained.

    val : u8{8} - Array containing the value
    bits : s32 - Number of bits that the value should be shifted to the right
    returns : Terror
    OK - If successful
    ERROR - If an invalid parameter has been transmitted
    s64_cmp(val1, val2)

    Compares the 64 bit signed integer values val1 and val2

    val1 : u8{8} - Arrays containing the first value to be compared
    val2 : u8{8} - Arrays containing the second value to be compared
    returns : s32
    1 - val1 > val2
    0 - val1 == val2
    -1 - val1 < val2

    CHAR & STRING

    strnlen(str{}, const strCells_=sizeof str)

    Returns the number of characters in a zero terminated ascii/packed string (without '\0')

    str{} : astr - Character string for which the length has to be determined
    strCells_ : s32 - Number of cells occupied by string
    returns : s32
  • Number of characters without the final '\0' or
  • Total size of str (bytes/chars) if no terminating zero '\0' found
    • It is recommended to use this function instead of strlen()
    wstrnlen(str[], const strCells_=sizeof str)

    Returns the number of characters in a zero terminated wide/unpacked string (without '\0')

    str[] : wstr - Character string for which the length has to be determined
    strCells_ : s32 - Number of cells occupied by string
    returns : s32
  • Number of characters without the final '\0' or
  • Total size of str (bytes/chars) if no terminating zero '\0' found
    • strlen(const string[])

    Returns the number of characters in a zero terminated string (without '\0')

    For safety reasons, it's recommend to use strnlen() and wstrnlen() instead.
    string[] : astr - Character string for which the length has to be determined
    returns : s32 - Number of characters without the final '\0'
    sprintf(dest[], maxlength=sizeof dest, const format[], {Float,Fixed,_}:...)

    Saves the transferred format string in the array dest. The mode of operation of the functions corresponds to that of the "snprintf" function of the standard ANSI-C implementation.

  • If resulting string is longer than <dest>'s size, the very last character is set to terminating zero.
  • <dest> size is always rounded up to full multiple of 4.
    • dest : astr - Array to store the formatted result
    maxlength : s32 - Maximum number of characters that the array dest can store
    format : astr - The format character string to be used (C-style formatting codes):
    %b - Number in binary radix
    %c - Character
    %d - Number in decimal radix
    %f - Floating point number
    %s - String
    %x - Number in hexadecimal radix
    ...:s32|f32|astr - Additional arguments.
    Depending on the format string, the function may expect
    a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.
    returns : s32
    >=0 - Number of characters that would have been written if the array <dest> had been long enough (without '\0').
    -1 - In the event of a fault
    The array <dest> is always assigned a final zero. The length of the array <dest> cannot be exceeded.
    strcpy(dest[], const source[], maxlength=sizeof dest)

    Copies the source character string to the array dest (including '\0').

    dest : astr - Array to store the character string that should be copied
    source : astr - Character string that should be copied
    maxlength : s32 - Size (in cells) of the array to store the character string to be copied - OPTIONAL
    returns : s32 - Number of copied characters
    strcat(dest[], const source[], maxlength=sizeof dest)

    Adds the source character string to the dest character string (including '\0')

    Both strings must be zero-terminated.
    dest : astr - Array to store the result. This array already contains one character string to which the source character string should be added.
    source : astr - Character string that should be added to the character string included in the array dest
    maxlength : s32 - Size (in Cells) of the array to store the result - OPTIONAL
    returns : s32 - Number of added characters
    strcmp(const string1[], const string2[], length=cellmax)

    Compares character string1 and string2

    Both strings must be zero-terminated.
    string1 : astr - The first of the two character strings that are to be compared
    string2 : astr - The second of the two character strings that are to be compared
    length : s32 - The maximum number of characters that should be taken into consideration during the comparison - OPTIONAL
    returns : s32
    1 - string1 > string 2
    0 - Both of the character strings are the same (at least the length that is taken into account)
    -1 - string1 < string 2
    strchr(const string[], char)

    Searches for a character (first occurrence) in a character string

    string : astr - Character string that should be searched
    char : u8 - Character that the search is looking for
    returns : s32
    -1 - If the character that the search is looking for is not included in the character string
    >=0 - Array index of the character that the search is looking for (first character occurring in the character string)
    strrchr(const string[], char)

    Searches for a character (last occurrence) in a character string

    string : astr - Character string that should be searched
    char : u8 - Character that the search is looking for
    returns : s32
    -1 - If the character that the search is looking for is not included in the character string
    >=0 - Array index for the character that the search is looking for (last character occurring in the character string)
    strspn(const string1[], const string2[])

    Searches for the position of the first character in string1 that is

    not included in the character string of permitted characters (string2).
    string1 : astr - Character string that should be searched
    string2 : astr - Character string of permitted characters
    returns : s32
  • Length of string1 if no forbidden characters are found
  • Position of the first character in the character string that should be searched that is not included in the character string of permitted characters
    • strcspn(const string1[], const string2[])

    Searches for the position of the first character in string1 that is

    also included in the character string of permitted characters (string2).

    See similar function strpbrk() which has a slightly different result.

    string1 : astr - Character string that should be searched
    string2 : astr - Character string of permitted characters
    returns : s32
  • Length of string1 if no permitted character has been found
  • Position of the first character in the character string that should be searched that is also included in the character string of permitted characters.
    • strpbrk(const string1[], const string2[])

    Searches the array index of the first character that is also included in the character string of permitted characters.

    See similar function strcspn() which has a slightly different result.

    string1 : astr - Character string that should be searched
    string2 : astr - Character string of permitted characters
    returns : s32
    -1 - If no permitted character has been found
    >=0 - Array index of the first character in the character string that should be searched that is also included in the character string of permitted characters
    strstr(const string1[], const string2[])

    Searches character string2 in character string1

    string1 : astr - Character string to search in
    string2 : astr - Character string to search for
    returns : s32
    -1 - If character string2 that is being searched for is not included in string1
    >=0 - Array index where character string2 that is being searched for starts in string1
    atoi(const string[])

    Converts a character string into an integer representation using base 10

    Similar to strtol( str, 10)

    Function differs slightly from it's C variant.
    string : astr - Character string to be converted
    Strings > 128 bytes are not supported!
    returns : s32 - Integer value that corresponds to the character string
    strtol(const string[], base)

    Converts a character string into a value.

    Function differs slightly from it's C variant.
    string : astr - Character string to be converted
    Strings > 128 bytes are not supported!
    Parsing consumes as many characters as possible, up to the first char not matching with given base.
    base : s32 - Specifies the basis that must be used for the conversion
    2..36 - The specified basis is used
    0 - 8, 10 or 16 is used as the basis, depending on the character string to be converted
  • 8 - with a leading "0"
  • 16 - with leading "0x" or "0X"
  • 10 - default
    • returns : s32 - Value that corresponds to the character string
    Float:atof(const string[])

    Converts a character string into a float

    Decimal separator is always ".", no thousands separators supported.
    string : astr - Character string to be converted
    Strings > 128 bytes are not supported!
    Parsing consumes as many characters as possible, up to the first none-float char.
    returns : f32 - Float for which the numerical value corresponds to the character string
    memcpy_native(dst{}, const dstofs, const src{}, const srcofs, const bytes, const dst_cells=sizeof dst, const src_cells=sizeof src)

    Copies bytes from one buffer to another one

    dst{} : u8 - Target buffer to which the data should be copied
    dstofs : s32 - Position (byte offset) in the target buffer to which the data should be copied
    src{} : u8 - Source buffer from which the data should be copied
    srcofs : s32 - Position (byte offset) within the source buffer from which the data should be copied
    bytes : s32 - Number of bytes that should be copied
    dst_cells : s32 - Size (in cells) of the target buffer - OPTIONAL
    src_cells : s32 - Size (in cells) of the source buffer - OPTIONAL
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • If one of the two byte offsets or the number of bytes to be copied is < 0
  • If the byte offsets refer to a byte outside the relevant buffer
  • If the reading was to exceed the source buffer (i.e. "Source byte offset" + "Number of bytes" would refer to a byte outside the source buffer)
  • If the reading was to exceed the target buffer (i.e. "Target byte offset" + "Number of bytes" would refer to a byte outside the target buffer)
  • If invalid buffers were transferred
    • memset_native(dst{}, const dstofs, const srcval, const bytes, dstcells=sizeof dst)

    Writes the desired value into the individual bytes of the transferred buffer

    dst{} : u8 - Buffer in which the bytes should be set to the desired value
    dstofs : s32 - Position (byte offset) within the transferred buffer from which the bytes should be set to the desired value
    srcval : s32 - Value to which the individual bytes should be set
    bytes : s32 - Number of bytes that should be set to the desired value
    dstcells : s32 - Size (in cells) of the transferred buffer - OPTIONAL
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • The byte offset is < 0
  • The byte offset refers to a byte outside the buffer
  • If an invalid buffer was transferred
    • memcmp_native(const src1{}, const src1ofs, const src2{}, const src2ofs, bytes, src1cells=sizeof src1, src2cells=sizeof src2)

    Compares two buffers, byte for byte

    src1{} : u8 - Buffer #1
    src1ofs : s32 - Position (byte offset) within buffer #1 from which the bytes should be compared
    src2{} : u8 - Buffer #2
    src2ofs : s32 - Position (byte offset) within buffer #2 from which the bytes should be compared
    bytes : s32 - Number of bytes that should be compared
    src1cells : s32 - Size (in cells) of buffer #1 - OPTIONAL
    src2cells : s32 - Size (in cells) of buffer #2 - OPTIONAL
    returns : Terror
    >0 - Buffer #1 > Buffer #2
    0 - The content of both of the buffers is the same (at least the bytes that are taken into account)
    <0 - Buffer #1 < Buffer #2
    tolower(c)

    Converts a character into lower case

    c : char - Character that should be converted to lower case
    returns : char - The lower case variant of the transferred character, if available, or the unchanged character code of "c" if the letter "c" does not have a lower case equivalent.
    toupper(c)

    Converts a character into upper case

    c : char - Character that should be converted to upper case
    returns : char - The upper case variant of the transferred character, if available, or the unchanged character code of "c" if the letter "c" does not have a upper case equivalent.

    CRC & HASH

    CRC16(data{}, len, initial=0xFFFF)

    Returns the calculated modbus CRC16 of the transferred data.

    data{} : u8 - Array that contains the data for which the CRC16 should be calculated
    len : s32 - Number of bytes that must be taken into consideration during the calculation
    initial : s32 - Initial value for calculating the CRC16 - OPTIONAL
    returns : s32 - Calculated CRC16
    CRC32(data{}, len, initial=0)

    Returns the calculated Ethernet CRC32 of the transferred data.

    data{} : u8 - Array that contains the data for which the CRC32 should be calculated
    len : s32 - Number of bytes that must be taken into consideration during the calculation
    initial : s32 - Initial value for calculating the CRC32 - OPTIONAL
    returns : s32 - Calculated CRC32
    TMD5_Ctx:

    Context structure for the MD5 calculation

    init : s32 - After being set to "0", the context structure can be used to calculate a new hash. If a calculation should be implemented by calling up the MD5() function repeatedly, there must not be write access to this element.
    tmp[22] : s32 - No write access permitted, for internal use only
    MD5(data{}, len, hash{16}, ctx[TMD5_Ctx] = [0])

    Calculates the MD5 hash for the transferred data. If the hash for a data block should be calculated by calling up this function several times (e.g. when receiving data in blocks), then the same context structure must be transferred every time the function is called up. The context structure must not be changed between function call-ups. If the hash can be calculated by calling up the function once (e.g. complete data block is already available), then it is not necessary to transfer its own context structure.

    data{} : u8 - Array that contains the data for which the MD5 hash should be calculated
    len : s32 - Number of bytes that must be taken into consideration during the calculation
    hash{16} : u8 - Array to store the calculated 128-bit hash value
    ctx : TMD5_Ctx - Context structure for the MD5 calculation – OPTIONAL (required only if calculation uses multiple calls to MD5() ).

    RUNTIME

    caniuse(const funcname{})

    Checks whether the required rapidM2M device API function is supported by the device firmware.

    This is a failsafe alternative to the exists() function and is supported on every rapidm2m firmware version.
    funcname : astr - Name of the required rapidM2M device API function
    returns : bool
    true - If the function is available
    false - If the device firmware does not support the function
    It is recommended to use this function instead of exists()
    getapilevel()

    Issues the implemented API level of the script engine.

    returns : s32 - Implemented API level of the script engine
    1 - Initial functionality
    2 - Added function 'exists()' to check availability of runtime function
    3 - Added function 'loadmodule()' to load a device logic module
    exists(const name[])

    Checks whether the required rapidM2M API function is supported by the device firmware.

    Use getapilevel() upfront to check if exists() is avilable with your firmware version.
    Use the improved method caniuse() instead!
    name[] : astr - Name of the required rapidM2M API function
    returns : bool
    true - If the function is available
    false - If the device firmware does not support the function
    loadmodule(mod{})

    Loads a script module at the runtime. This enables the script engine to be extended by its own native functions. The implementation of operations as a native function means that processing speeds can be increased significantly in comparison to the implementation in pawn. A script module can contain several native functions. After calling up this function, the native functions contained in the script module can be used in the same way as the standard functions available in the script engine.

    mode{} : u8 - Byte array that contains the script module to be loaded.
    returns : Terror
    OK - If successful
    ERROR - If an error occurs, see Terror
    TRTM_Data:

    Information regarding the runtime measurement

    runtime : s32 - Determined runtime in [ms]
    instructions : s32 - Number of executed instructions
    tmp[3] : s32 - For internal use, no write access permitted
    rtm_start(), rtm_stop()
    rtm_start(measurement[TRTM_Data])

    Starts a runtime measurement.

    Execution of concurrent measurements is not allowed.
    measurement : TRTM_Data - Structure for storing the information regarding a runtime measurement
    This structure must be persistent from calling up rtm_start() to calling up rtm_stop().
    returns : Terror
    OK - If successful
    ERROR - If an error occurs, see Terror
    rtm_stop(measurement[TRTM_Data])

    Stops the runtime measurement and calculates the time in [ms] since the rtm_start() function was called up and the instructions executed since then. The determined values are written in the ".runtime" and ".instructions" elements of the transferred structure to record the information regarding a runtime measurement.

    measurement : TRTM_Data - Structure for storing the information regarding a runtime measurement
    This structure must be persistent from calling up rtm_start() to calling up rtm_stop().
    returns : Terror
    OK - If successful
    ERROR - If an error occurs, see Terror
    getRuntime(ticks=10)

    Returns the ticks since the device booted

    ticks : s32 - Desired resolution ( [1|10|100|256] ticks per second ) - OPTIONAL
    Only use [1|10|100|256].
    returns : s32 - Ticks since the device booted. Timerange depends on ticks parameter and S32_MAX
    ticksresolutionrange
    11 second68 years
    10100ms6.8 years
    10010ms249 days
    2561/256s97 days
    Negative results represent u32 with MSB set. Considering this MSB issue, the effective ranges are twice of what stated above.

    INTERPOLATION

    TablePoint:

    Two-column reference point table, integer data type

    key : s32 - Column that is searched
    value : s32 - Column with the result values that need to be returned
    TablePointF:

    Two-column reference point table, float data type

    key : f32 - Column that is searched
    value : f32 - Column with the result values that need to be returned
    TTableResults:

    Error codes for the "CalcTable" and "CalcTableF" functions

    TAB_ERR_FLOOR = -1 - Searched value lower than the first table entry -> output value is set to the first table entry.
    TAB_ERR_CEIL = -2 - Searched value higher than the last table entry -> output value is set to the last table entry.
    CalcTable(key, &value, const table[][TablePoint], size = sizeof table)

    Searches for a certain value in the "key" column of the transferred reference point table and supplies the relevant value from the "value" column in the table. If the searched value is between two reference points, the returned value is interpolated linearly between the two adjacent values in the "value" column (linear equation: y = k*x + d). Non-linear characteristic curves (e.g. connection between ADC value -> temperature) can be reproduced with this function.

    key : s32 - Value that is used for the search
    value : s32 - Includes the result of the calculation by the function
    table[] : TablePoint - The table that is searched must be a "TablePoint" type table.
    size : s32 - Number of rows in the table
    returns : TTableResults
    OK - If the relevant value was found
    TAB_ERR_FLOOR - If the searched value is lower than the first table entry. "value" contains the first table entry.
    TAB_ERR_CEIL - If the searched value is higher than the last table entry. "value" contains the last table entry.
    <OK - If another error occurs, see Terror
    CalcTableF(Float:key, &Float:value, const table[][TablePointF], size = sizeof table)

    Searches for a certain value in the "key" column of the transferred reference point table and supplies the relevant value from the "value" column in the table. If the searched value is between two reference points, the returned value is interpolated linearly between the two adjacent values in the "value" column (linear equation: y = k*x + d). Non-linear characteristic curves (e.g. connection between ADC value -> temperature) can be reproduced with this function.

    key : f32 - Value that is used for the search
    value : f32 - Includes the result of the calculation by the function
    table[] : TablePointF - The table that is searched must be a "TablePointF" type table.
    size : s32 - Number of rows in the table
    returns : TTableResults
    OK - If the relevant value was found
    TAB_ERR_FLOOR - If the searched value is lower than the first table entry. "value" contains the first table entry.
    TAB_ERR_CEIL - If the searched value is higher than the last table entry. "value" contains the last table entry.
    <OK - If another error occurs, see Terror

    DEVICE INFO

    heapspace()

    Supplies the amount of free memory available for heap and stack.

    The stack and the heap have a joint memory area.
    returns : s32 - The number of free bytes that remain for the stack and heap.
    rM2M_GetId(id[TrM2M_Id], len=sizeof id)

    Provides the information to identify the module/device.

    id : TrM2M_Id - Structure for storing the information to identify the module/device
    len : s32 - Size (in cells) of the structure to store the information - OPTIONAL
    returns : Terror
    >0 - Size (in cells) of the structure used to store the information
    ERROR - If the address and/or length of the ID structure are invalid (outside the script data memory)
    <OK - If another error occurs, see Terror
    The firmware of a module/device detects if a script is being used for which the function only has one transfer parameter (older include file is being used) and for compatibility reasons therefore returns "OK" instead of the size of the structure for storing the information.
    TrM2M_Id:

    Information for identifying the module/device

    string : astr{50} - rapidM2M module identification (e.g. "rapidM2M M2 HW1.4")
    module : astr{10} - rapidM2M module type (e.g. "M2")
    hwmajor : s32 - Hardware: Major version number
    hwminor : s32 - Hardware: Minor version number
    sn : bin{8}:s32 - Device serial number (binary) in BIG endian format, e.g.: "010146AF251CED1C" --> "01" in sn{0}, "1C" in sn{7}
    fwmajor : s32 - Firmware: Major version number
    fwminor : s32 - Firmware: Minor version number
    ctx : astr{50} - Site title (context); Empty string if no context available

    FUNCTION ARGUMENTS

    numargs()
    Returns the number of arguments transferred to a function. This is useful within functions with a variable list of arguments.
    returns : s32 - The number of arguments that have been transferred to a function.
    getarg(arg, index=0)

    This function supplies an argument from a variable argument list. If the argument is an array, the "index" specifies the index of the required array element.

    arg : s32 - The sequence number of the argument. Use 0 for the first argument.
    index : s32 - Index if "arg" refers to an array
    returns : s32 - The value of the argument.
    setarg(arg, index=0, value)

    This function sets an argument in a variable argument list. If the argument is an array, the "index" specifies the index of the required array element.

    arg : s32 - The sequence number of the argument. Use 0 for the first argument.
    index : s32 - Index if "arg" refers to an array
    value : s32 - Value to which the argument should be set
    returns : boolean
    true - If the value could be set
    false - If the argument or index are invalid

    SMS

    TSms_Callback(
    public func( const SmsTel[], const SmsText[]);
    Function to be provided by the device logic developer, that is called up if an SMS is received(registered with rM2M_SmsInit() ).
    SmsTel[] : astr - String that contains the telephone number of the sender of the SMS
    SmSText[] : astr - String that contains the content of the SMS
    rM2M_SmsInit(funcidx, config)

    Initialises SMS receipt.

    funcidx : s32 - Index of the public function that should be called up if an SMS has been received.

    of the function (see TSms_Callback):
    public func( const SmsTel[], const SmsText[]);
    If an SMS that is longer than 160 characters is received, it is discarded immediately. The specified public function is not called up.
    config : s32 - Reserved for extensions
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    If the device is in "online" mode no SMS can be processed.
    rM2M_SmsClose()

    Deactivates SMS receipt.

    returns : Terror
    OK

    FILE TRANSFER

    filetransfer:
    Major API:
    • FT_Register()
    • TFT_Processor
    • FT_Unregister()
    • FT_Error()
    TFT_Info:

    Properties of a file entry

    name{256} : astr - Name of the file
    stamp : stamp32 - Time stamp of the file (seconds since 31.12.1999)
    stamp256 : stamp40 - Fraction of the next started sec. (resolution 1/256 sec.)
    size : s32 - File size in byte
    crc : s32 - Ethernet CRC32 of the file
    flags : TFT_Flags - File flags, see TFT_Flags
    TFT_Flags:

    File flags

    FT_FLAG_READ = 0x0001 - File can be read by the server
    FT_FLAG_WRITE = 0x0002 - File can be written by the server
    FT_FLAG_NODE = 0x0004 - File nodes (required to entitle the server to create a new file)
    FT_FLAG_SYSTEM = 0x0008 - System file (cannot be used by the device logic)
    TFT_Cmds:

    File transfer command

    FT_CMD_NONE = 0
    FT_CMD_UNLOCK = 1 - File transfer session terminated. The server releases the block again.
    FT_CMD_LIST = 2 - The server requests the properties of a file.
    FT_CMD_READ = 3 - The server requests a part of a file.
    FT_CMD_STORE = 4 - The server requests a file to be written.
    FT_CMD_WRITE = 5 - The server provides a block to be written in a file.
    FT_CMD_DELETE = 6 - The server requests a file to be deleted.
    FT_CMD_ENUM = 7 - The server requests the properties of a file that are part of a file node.
    FT_CMD_RETR = 8 - The server requests a file that is part of a file node.
    FT_CmdToString(cmd)

    Converts a file transfer command into a string

    cmd : TFT_Cmds - File transfer command to be converted
    returns : astr - String corresponding to the transferred file transfer command
    TFT_Callback(
    public func(id, cmd, const data{}, len, ofs);
    Function to be provided by the device logic developer, that is called up when a file transfer command is received (registered with FT_Register() or FT_RegisterEnum() ). The callback function must be able to handle all file transfer commands (see TFT_Cmds).
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    cmd : TFT_Cmds - File transfer command that was received from the system and that has to be processed by the callback function
    FT_CMD_UNLOCK, FT_CMD_DELETE
    no parameters, no function expected
    FT_CMD_LIST
    no parameters; expects FT_SetPropsExt() to be called withing 15s
    FT_CMD_READ
    len and ofs; expects FT_Read() to be called within 15s
    FT_CMD_STORE
    data and len; expects FT_Accept() to be called within 15s
    FT_CMD_WRITE
    data, len and ofs; expects FT_Written() to be called within 15s
    FT_CMD_ENUM
    ofs, no function expected
    FT_CMD_RETR
    data and len, no function expected
    data{} : u8 - This parameter is only relevant when the following file transfer commands are received:
    FT_CMD_STORE
    Array that contains the properties of the file that should be newly created. Structure:
    OffsetBytesExplanation
    04Time stamp of the file
    84File size in byte
    124Ethernet CRC32 of the file
    162File flags
    18256File name
    FT_CMD_WRITE
    Array that contains the data received from the rapidM2M Portal server.
    FT_CMD_RETR
    Name of a file (ASCII) that is part of a file node and was requested by the server.
    len : s32 - This parameter is only relevant when the following file transfer commands are received:
    FT_CMD_READ
    Number of bytes requested by the rapidM2M Portal server (max. 4kB).
    FT_CMD_STORE
    Size of the file property block received from the rapidM2M Portal server.
    FT_CMD_WRITE
    Number of bytes received from the rapidM2M Portal server.
    FT_CMD_RETR
    Length of the file name (number of characters excluding the final '\0').
    ofs : s32 - This parameter is only relevant when the following file transfer commands are received:
    FT_CMD_READ
    Byte offset within the file of the data block to be transferred to the rapidM2M Portal server.
    FT_CMD_WRITE
    Byte offset within the file of the data block received from the rapidM2M Portal server.
    FT_CMD_ENUM
    List index (starting with 0) for when the server requests the properties of a file that belongs to a file node 1)
    1) Upon receipt of the file transfer command "FT_CMD_ENUM", the FT_SetPropsExt() function can be used to set the properties of a file that should be assigned to the current file node. This means that a file is assigned to the file node. Following the first "FT_CMD_ENUM" command, the system sends further "FT_CMD_ENUM" commands until the device logic developer indicates that they do not want to assign any more files to the current file node. The developer must indicate this by setting the length for the "TFT_Info" structure (i.e. the "len" parameter) to 0 when setting the file properties via the FT_SetPropsExt() function.
    FT_Register(const name{}, id, funcidx)

    Registers a file made available by the device logic.

    name{} : astr - Unique file name
    id : s32 - Unique identification with which the file is subsequently referenced (freely selectable)
    funcidx : s32 - Index of the public function that should be called up if a file transfer command has been received.

    Type of the function (see TFT_Callback):
    public func(id, cmd, const data{}, len, ofs);
    All file transfer commands (see TFT_Cmds) must be handled by this public function.
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_RegisterEnum(id, funcidx, props[TFT_Info], len=sizeof props)

    Registers a file node made available by the device logic. Several files can be managed via a file node.

    id : s32 - Unique identification with which the file node is subsequently referenced (freely selectable)
    funcidx : s32 - Index of the public function that should be called up if a file transfer command has been received.

    Type of the function (see TFT_Callback):
    public func(id, cmd, const data{}, len, ofs);
    All file transfer commands (see TFT_Cmds) must be handled by this public function.
    props : TFT_Info - Structure that contains the properties of a file entry for the file node
    .name - Those parts of the file node name that are not wildcards, must also appear in the names of the files that should be managed with the file node (wildcard matching), so that the read and write operations are accepted.
    .flags - Read/write flags as required; node flag mandatory
    len : s32 - Size (in cells) of the structure that contains the properties of a file entry – OPTIONAL
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_Unregister(id)

    Removes a file from the registration. The file is no longer available for the file transfer.

    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_SetPropsExt(id, props[TFT_Info], len=sizeof props)

    Sets the properties of a file (extended format).

    This function must be called up following receipt of a "FT_CMD_LIST" command.
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    props : TFT_Info - Structure that contains the properties of a file entry
    len : s32 - Size (in cells) of the structure that contains the properties of a file entry – OPTIONAL
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_Read(id, const data{}, len))

    Transmits the data to the system, to transfer it to the rapidM2M Portal server. The data must be provided by the callback function specified via FT_Register().

    This function must be called up following receipt of a "FT_CMD_READ" command.
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    data{} : u8 - Array that contains the data that should be transmitted to the system to be transferred to the rapidM2M Portal server
    len : s32 - Number of bytes to be transferred
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_Accept(id, newid=-1)

    Accepts the file that the rapidM2M Portal server wants to write. It is a new file if the transferred unique identification number ("id" parameter) refers to a file node. In this case, an unique identification number ("newid" parameter) must be assigned to the new file. The new file must also be registered via the FT_Register() function. The file properties that were transmitted by the system to the callback function (see TFT_Callback) must be saved via the FT_SetProps() function.

    This function must be called up following receipt of a "FT_CMD_STORE" command.
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    newid : s32 - Unique identification for the new file that should be created (-1 if it is not a new file) - OPTIONAL
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_Written(id, len)

    Confirms that the data received from the rapidM2M Portal server has been written. The actual writing process must be executed via the callback function specified via FT_Register(). The data that is to be written is transmitted to the callback function by the system (see TFT_Callback).

    This function must be called up following receipt of a "FT_CMD_WRITE" command.
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    len : s32 - Number of written bytes
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    FT_Error(id)

    Used to display a file handling error and terminates any file command.

    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror

    HARDWARE PLATFORM SPECIFIC

    M22X:

    rapidM2M M22x hardware platform:
    An explanation of the functions only available on the "rapidM2M M22x" hardware platform can be found in the rapidM2M M22x section.

    M23X:

    rapidM2M M23x hardware platform:
    An explanation of the functions only available on the "rapidM2M M23x" hardware platform can be found in the rapidM2M M23x section.

    M2BLEGW:

    BLE & LTE-M Gateway hardware platform:
    An explanation of the functions only available on the "BLE & LTE-M Gateway" hardware platform can be found in the BLE & LTE-M Gateway section.

    M2EASYV3:

    myDatalogEASY V3 hardware platform:
    An explanation of the functions only available on the "myDatalogEASY V3" hardware platform can be found in the myDatalogEASY V3 section.

    M2EASYIOT:

    myDatalogEASY IoT hardware platform:
    An explanation of the functions only available on the "myDatalogEASY IoT" hardware platform can be found in the myDatalogEASY IoT section.

    NRF91:

    rapidM2M NRF91 hardware platform:
    An explanation of the functions only available on the "rapidM2M NRF91" hardware platform can be found in the rapidM2M NRF91 section.

    EXPERT

    Advanced_Config:
    The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings add the following block to the main.dde file.
    /** ---------------------------------------------------------------------------- * ~stdlib: Advanced Config * ----------------------------------------------------------------------------- * * Use this block to adapt the advanced configuration settings: * */ #define COUT_BUF_CHARS 1024 // Total size of temporary console output buffer // A single #log(), #watch() or assert() must not exceed this number of characters!

    The settings mentioned in this chapter should only be changed if really required (e.g. power saving required). To adapt the settings add the following code block to your device logic. The code block should be executed directly at program startup.
    /** ---------------------------------------------------------------------------- * ~stdlib: Advanced Config * ----------------------------------------------------------------------------- * * Use this block to adapt the advanced configuration settings: * */ stdlibOptions.coutAliveSeconds = 5 // Max. time [sec] of inactivity on debug/console output.
    COUT_BUF_CHARS - 1024 (default)

    Total size of temporary console output buffer used to hold results of #log(), #watch(), assert() formatting

    A single #log(), #watch() or assert() must not exceed this number of characters!
    stdlibOptions:

    Global settings for ~stdlib

    .coutAliveSeconds=5 - Max. time [sec] of inactivity on debug/console output.
    An alive frame is sent to TESTbed, if there is no other activity.
    >0 - An alive frame is sent every "coutAliveSeconds" sec. to the TESTbed, if there is no other activity.
    0 - Alive ping is disabled

    DEPRECATED

    rM2M_GSMGetRSSI(flags=0)

    Returns the GSM/UMTS/LTE signal strength.

    Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The rM2M_GetRSSI() function should be used as an alternative.
    flags : s32 - Configuration flags for the signal strength measurement
    RM2M_RSSI_EXTENDED_VALUE = 0b0000000001 - If set, the extended value range for the return of the signal strength is used
    returns : s32 - Signal strength in [dBm]
    RM2M_RSSI_EXTENDED_VALUE not set:
  • Maximum value range: -127 to 127
  • Out of range at: -128
    • RM2M_RSSI_EXTENDED_VALUE set:
  • Maximum value range: -32767 to 32767
  • Out of range at: -32768
    • GSM values range from -113 to -51 dBm.
    UMTS values range from -116 to -54 dBm.
    LTE values range from -141 to -44 dBm.
    rM2M_SetPacked(data{}, pos, &{Float,Fixed,_}:value, size=4, bool:bigendian=false)

    Writes the transferred value to a specified position in an array.

    Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects as the signed data types might lead to problems. The rM2M_Pack() function should be used as an alternative.
    data{} : u8 - Array that should be used as a data area for a data record or a configuration
    pos : s32 - Byte offset within the array to determine the position where the value should be written
    value : f32|s32 - Value that should be written in the array
    size : 1|2|3|4 - Number of bytes that should be used for the value to be written
    bigendian : bool - Settings for the byte sequence that should be used when writing the value:
    true - "Big endian" is used
    false - "Little endian" is used
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror

    Additional explanation on the byte sequence:

    In the following example, the whole number 439.041.101 is saved as a 32-bit integer value from memory address 10000.

    Big endianLittle endian
    AddressesHexDezBinaryHexDezBinary
    100001A26000110104D7701001101
    100012B43001010113C6000111100
    100023C60001111002B4300101011
    100034D77010011011A2600011010
    rM2M_GetPacked(const data{}, pos, &{Float,Fixed,_}:value, size=4, bool:bigendian=false)

    Supplies the value that is located at the specified position in an array.

    Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects as the signed data types might lead to problems. The rM2M_Pack() function should be used as an alternative.
    data{} : u8 - Array that should be used as a data area for a data record or a configuration
    pos : s32 - Byte offset within the array to determine the position from which the data should be read
    value : f32|s32 - Variable to store the data to be read
    size : 1|2|3|4 - Number of bytes that should be read
    bigendian : bool - Specifies how the packed data must be interpreted:
    true - The data is saved in "Big endian" format in the array.
    false - The data is saved in "Little endian" format in the array.
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror

    Additional explanation on the byte sequence:

    In the following example, the whole number 439.041.101 is saved as a 32-bit integer value from memory address 10000.

    Big endianLittle endian
    AddressesHexDezBinaryHexDezBinary
    100001A26000110104D7701001101
    100012B43001010113C6000111100
    100023C60001111002B4300101011
    100034D77010011011A2600011010
    FT_SetProps(id, stamp, size, crc, flags)

    Sets the properties of a file.

    This function must be called up following receipt of a "FT_CMD_LIST" command.
    Although this function will still be supported for the purpose of downward compatibility, it should no longer be used for new projects. The FT_SetPropsExt() function should be used as an alternative.
    id : s32 - Unique identification with which the file is referenced (specified during registration, see FT_Register() )
    stamp : stamp32 - Time stamp of the file (seconds since 31.12.1999)
    size : s32 - File size in byte
    crc : s32 - Ethernet CRC32 of the file
    flags : TFT_Flags - File flags
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    funcidx(const name[])

    Supplies the index of a public function. Used to register callbacks for the Pawn runtime environment.

    It's recommended to use #callback instead
    name : astr[] - Name of the public function, e.g.
    public func()
    returns : s32
    -1 - If there is no function with the transferred name
    >0 - Index of the public function
    print(const string[])

    Prints the specified string to the standard output.

    It's recommended to use #log instead
    It's recommended to call salve() to increase the console buffer before using print().
    string : astr - The character string to be issued. This can include escape sequences.
    returns : s32
    OK - Always OK.
    printf(const format[], {Float,Fixed,_}:...)

    Prints the transferred format string to the standard output. The mode of operation of the functions corresponds to that of the standard ANSI-C implementation.

  • Characters may get lost, if console output buffer overflows.
  • Use sprintf() to write to a string buffer instead of the console.
    • It's recommended to use #log instead
    It's recommended to call salve() to increase the console buffer before using printf().
    format : astr - The format character string to be used (C-style formatting codes):
    %b - Number in binary radix
    %c - Character
    %d - Number in decimal radix
    %f - Floating point number
    %s - String
    %x - Number in hexadecimal radix
    ... : s32|f32|astr - Additional arguments.
    Depending on the format string, the function may expect a sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.
    returns : s32
    >0 - Number of printed characters
    ERROR - If not successful

    DDE - Data Descriptor

    Description

    Standard library for the rapidM2M Studio ecosphere

    INTRODUCTION

    dde_basics:

    Define the interface data structures for the rapidM2M application model. Typical content:

    // write a line-comment anywhere /* or a block-comment spanning over multiple lines */ // header section - define constants #define name value // body section - define containers and their fields #config0 mycontainer up // define a container fname … // define a field
    Available containers and recommended usage:
    Single instance containers
    #config0 status up title="STATUS upload" // high frequency, tiny #config1 status2 up title="STATUS#2 upload" // medium frequency, verbose #config2 status3 up title="STATUS#3 upload" // low frequency, verbose #config3 info up title="INFO upload" // very low frequency #config4 - preferably used for upward transmission, no further recommendations yet #config5 - preferably used for downward transmission, no further recommendations yet #config6 usrcmds down title="USRCMDS download" // high frequency #config7 usrcfg down title="USRCFG download" // medium frequency #config8 usrcfg2 down title="USRCFG#2 download" // low frequency #config9 syscfg down title="SYSCFG download" // very low frequeny (incl. dbg cfg)
    Time series containers
    #histdata0 measurements up title="MEASUREMENTS" // primary measurements time-series #histdata1 measurements2 up title="MEASUREMENTS#2" // secondary measurements time-series #histdata2 ... #histdata6 - no recommendations yet #histdata7 applog up title="APPLOG" // app log time-series - tiny, most import app events, user actions,... #histdata8 dbglog up title="DBGLOG" // debug log time-series - verbose, additional events with some more details #histdata9 dbgtrace up title="DBGTRACE" // raw dump time-series - very verbose for local interface tracing
    Other containers
    #alerts #aloha

    REFERENCE

    #define(

    define a constant

    #define name value
    >> See ~auto.dde for automatically generated constants.
    name - Name of the constant. Just cite "@name" to use it in the container definitions.
    value - Number or "string value"

    There are several reserved names /w special meaning:
    Encode array/struct to be compatible with the POV's built-in CMS
    "_dde_cms_ 2" changes REST APIs naming scheme!
    #define _dde_cms_ 2 // use "_" instead of ".[]" for fieldname encoding #define _dde_cms_ 1 // Issue warnings if DDE contains incompatibile declarations #define _dde_cms_ 0 // Don't care about the CMS - we do not use it (this is the default)
    dlo/~auto-dde.inc formatting
    Minifying the file may be helpful in case of pawncc linebuffer overflows due to high number of fields per container.
    #define _auto_dde_minify_ 1 // minify the file #define _auto_dde_minify_ 0 // do not minify the file (this is the default)
    deploy/dde.xml formatting
    #define _dde_minify_ 0 // formatted output /w source code include #define _dde_minify_ 1 // formatted output, w/o source code #define _dde_minify_ 2 // max. minification (this is the default)
    #configA(

    → #configZ

    #configB(

    → #configZ

    #configC(

    → #configZ

    #configZ(

    define a backend-only, single instance container

    #configZ cname [attr=value] // comment // ... the corresponding field-definition must follow below
    Do not specify the container's direction - it is implicitly always "backend-only".
    Z - configA, configB, configC
    cname - Used to address the container in your codes (must start with alpha character, followed by alpha, number or underscore, no spaces)
    attr=value - optional attributes, same as with → #configX
    #config0(

    → #configX

    #config1(

    → #configX

    #config2(

    → #configX

    #config3(

    → #configX

    #config4(

    → #configX

    #config5(

    → #configX

    #config6(

    → #configX

    #config7(

    → #configX

    #config8(

    → #configX

    #config9(

    → #configX

    #configX(

    define a versatile single instance container

    #configX cname cdirection [attr=value] // comment // ... the corresponding field-definitions must follow below.
    X - config0 … config9
    cname - Used to address the container in your codes (must start with alpha character, followed by alpha, number or underscore, no spaces)
    cdirection - Describes transport direction of the container between device and backend
    up - from device ⬈ backend, fixed length container
    down - from backend ⬊ device
    up+|down+ - Variable length container - useful to save transmission volume when a container transports data of highly varying length, e.g. trace data of some interface
    Special purpose - normally not used
    both|both+ - !!! just for legacy purpose - usage highly disadvised !!!
    none-be - aka
    backend-only - the container is available at the
    backend only; it's not transmitted, nor accessible at the device
    none-de - aka
    device-only - the container is available at the
    device only; it's not transmitted, nor accessible at the backend
    none - the container is
    not transmitted; it's accessible at backend and device, but never synchronized
    dlo-volatile
  • Applies only to #configX containers with direction up|up+|none|device-only
  • Use of ~uplink and ~dde library required.

    • See configx_volatile for details.

    #config0 status dlo-volatile

    or

    #config0 status dlo-volatile="lazy" // combine with DDE_xxx_persist()
    rM2M_CfgInit, rM2M_CfgFlush
    attr=value - optional attributes
    title = "my Title" - title to describe the containers content in the portal
    dlo = "wu" - unroll DLO write functions e.g. handover container fields as individual parameters to DLO write functions (instead of a compact DDE_xxx structure)
    // without dlo="wu" new buffer[DDE_mycontainer]; buffer.va= valueA; buffer.vb= valueB; DDE_mycontainer_write( buffer); // with dlo="wu" DDE_mycontainer_write( valueA, valueB);
    edit = 1 - userlevel required for editing (1=operator … 7=sys-admin, 99=reaonly on REST APIs) - for "down"/"down+" containers only!This container wide setting may be overruled by field specific settings.
    view = 1 - userlevel required for viewing (1=operator … 7=sys-admin)This container wide setting may be overruled by field specific settings.
    #histdata0(

    → #histdataX

    #histdata1(

    → #histdataX

    #histdata2(

    → #histdataX

    #histdata3(

    → #histdataX

    #histdata4(

    → #histdataX

    #histdata5(

    → #histdataX

    #histdata6(

    → #histdataX

    #histdata7(

    → #histdataX

    #histdata8(

    → #histdataX

    #histdata9(

    → #histdataX

    #histdataX(

    versatile time-series container

    #histdataX cname cdirection [attr=value] // comment // ... the corresponding field-definitions must follow below.
    X - histdata0 … histdata9
    cname - Used to address the container in your codes (must start with alpha character, followed by alpha, number or underscore, no spaces)
    cdirection - Describes transport direction of the container between device and backend
    up - from device to backend, fixed length container
    up+ - Variable length container - useful to save transmission volume when a container transports data of highly varying length, e.g. trace data of some interface
    attr=value - optional attributes
    title = "series" - see #configX
    dlo = "wu" - see #configX
    view = 1 - see #configX
    #alerts(

    enable alarms and warnings time series

    #alerts // ... the fields are already predefined (e.g. do not add your own field-definition!).
    This is a special purpose container with time-series, upward direction behaviour.
    #aloha(

    a special container to transport live data during put-into-operation procedures

    #aloha up va f32.3 // ... the corresponding field-definitions must follow below.
    This is a special purpose container with time-series, upward direction behaviour.
    It's heavily recommended to use the ~dde library for easy interfacing.
    Max. 10 fields are supported by the backend's portal view. You may specify more than this, but they won't be shown at the portal.
    Experimental: use #aloha up+ to deal with flexible length aloha container.
    fname(type [attr=value] // comment
    Define a field
    fname - Used to address the field in your codes (must start with alpha character, followed by alpha, number or underscore, no spaces)
    ftype - One of the predefined types below with optional extra specifiers (such as precision or size)
    s8|s16|s32|s64 - signed integer
    sa s8 // signed integer sb s16.3 // signed integer fixed comma 3 decimals
    u8|u16|u32 - unsigned integer
    ua u8 // unsigned integer ub u16.3 // unsigned integer fixed comma 3 decimals
    f16|f32|f64 - floating point
    fa f16 // float, hide decimal digits fb f32.3 // float, show 3 decimal digits
    astr|nstr|wstr|ustr|cstr - string
    za astr.20 // ANSI CP-1252 /w 20 chars zn nstr.20 // ANSI CP-1252 stored as utf-8 /w 20 bytes zw wstr.20 // Unicode utf-32 stored as utf-8 /w 20 bytes zu ustr.20 // Unicode utf-8 /w 20 bytes zc cstr.20 // ANSI any CP stored as binary /w 20 bytes
    bin - binary buffer
    buf bin.20 // binary buffer /w 20 bytes
    stamp32|stamp40 - timestamp /w 1second or 1/256second resolution
    // 1second resolution dts_utc stamp32 // POV prints in UTC dts_utc stamp32.utc // same as above dts_loc stamp32.local // POV prints in localtime (APIs use always UTC)
    // 1/256second resolution (e.g. 1 tick) dtt_utc stamp40 // POV prints in UTC dtt_utc stamp40.utc // same as above dtt_loc stamp40.local // POV prints in localtime (APIs use always UTC)
    attr=value - optional attributes, such as
    title = "my status" - title to describe the field in the portal
    units = "kg" - units information to be shown in default POV
    default = 123|"abc" - newly created sites are initialised to this value; fallback to all zero.
    editmask = "see below..."
    Format statements for displaying the field content on the interface of the server or input via the interface of the server.

    usable for strings (data type "astr", "nstr", "wstr" and "ustr", however not for "cstr")
    editmask="%COLORPICKER%"
    Creates a button that displays the currently selected colour. When clicking the button, a dialog field to set the desired colour appears. The dialog field returns the selected colour as a string in "RRGGBB" format, with the colour components being specified in hex.

    editmask="%HEX%"
    Creates an input field in which the string is displayed in hex format. Each byte of the string is therefore represented by two characters. For example, the letter 'a' is represented as "61".

    editmask="%MASKED%"
    Creates an input field whose content is masked with "asterisk" (e.g. for passwords and tokens). A button (eye icon) for switching between plain text and masking is displayed next to the input field.

    editmask="%MULTILINE%30%75"
    Creates a text field with 30 lines and 75 characters per line

    usable for numeric fields (data type "u8", "s8", "f32", ....)
    editmask="%2.0x"
    Creates an input field in which the numeric value is displayed in hex format. Each byte of the data type is therefore represented by two characters. The number after "%" must match the number of characters required to represent the data type (e.g. '4' for a "u16").
    When using this format statement, the "decpl" attribute must also be set to "-1" (i.e. decpl=-1).

    editmask="0=off;1=on"
    A dropdown list is created in which the text following the "=" is displayed for each entry instead of the value. Entries must be separated using a ";".
    The entries MUST NOT strart with '+' or '~'

    editmask="%CHECKBOX%"
    A checkbox is created.
  • 1 = tick set
  • not equal to 1 = tick not set
    • If the checkbox is used to display data and the device returns a value not equal to 1, the tick is also displayed as "not set". If the checkbox is used for data entry and the tick is not set, the checkbox returns 0.

    editmask="%CHECKBOX%5;10"
    A checkbox is created the same as for editmask="%CHECKBOX%", accept that the values for "tick set" (in this example 10) and "tick not set" (in this example 5 or not equal to 10) can be chosen. The note above is also valid in a similar way

    editmask="%TIME%s%hh:mm:ss"
    Creates an input field in which the numeric value is displayed in the specified time format (e.g. hh:mm:ss)
    After the segment "%TIME" it must be specified whether the value is saved in seconds (%s) or in minutes (%m). The time format follows after this specification. "%hh:mm:ss", %hh:mm" or "%mm:ss" are possible formats. Caution "%mm:ss" is not valid if the value is to be saved in minutes (%m).
    It is advisable to use the "units" attribute to specify the time format (e.g. hh:mm:ss) in which the value is displayed.

    usable for timestamps (data type "stamp32" and "stamp40")
    editmask="%DATETIMEPICKER%"
    Creates an input field in which the timestamp is displayed as date/time. When clicking on the input field, a dialog field to select date and time appears
    vofs = 1000 - → vscale
    ddeFieldRefs
    vscale = 2.5 - scale the raw value when showing on POV or passing through the REST APIs
    scaled = raw * vscale + vofs
    ddeFieldRefs
    decpl = 1 - number of decimal places to show (applies to POV and REST APIs)
    ddeFieldRefs
    min = 0 - available on numeric values only; disables auto-scaling of lower-range on charts
    max = 100 - available on numeric values only; disables auto-scaling of higher-range on charts
    chmode = 1|2|3|6*|12 - defines how values are treated up on aggregation; applies to numeric histdata fields only
  • 1 = digital - treatment as digital value; the raw value should be 0 or 1
  • 2 = day counter - a counter which is reset once per day
  • 3 = interval counter - a counter which is reset on each recording
  • 6 = analogue (default) - a "normal" measurement value, e.g. temperature
  • 12 = infinite counter - a counter which is never reset, e.g. water- or electricity meter
    • edit = 1 - userlevel required for editing (1=operator … 7=sys-admin, 99=reaonly on REST APIs) - for "down"/"down+" containers only!, overwrites the container's
    edit= setting
    view = 1 - userlevel required for viewing (1=operator … 7=sys-admin), overwrites the container's
    view= setting
    index = 7 - change field order in POV default view
    POV shows all fields with index set first.
    >=1 = sort order, 1=top most (gaps in numbering are allowed)
    -1 = hide this field in POV (but it's still available on REST APIs)
    -2 = hide this field from POV, REST APIs and uplink synchronisation; this is similar to not define the field
    dlorw = skip - do not handle this field in DLO's ~dde library;
    Required for any overlay/shadow fields since DLO is not able to handle them yet.
    dlorw = < type> - override field-type in DLO auto codes, typically used for binary pass through of floats
    The interface codes provided by the ~dde library treat any f16/f32 field as native Pawn Float:, including 16/32bit conversions necessary for f16.
    If your values come already in as binary encoded f16 or f32 (for example from some external system) you may prefer to just pass them through DLO on the binary level "as it is".
    <type> - any compatible type of same size as the field's base type.
    xxx f32 dlorw=u32 // u32 in DLO, f32 in BLO and POV zzz f16 dlorw=u16 // u16 in DLO, f16 in BLO and POV
    ddeFieldRefs:
    Some attributes may become dynamic by referring to a field.
    The reference must point to another container, and not to the referrer container itself.
    The reference follows this structure:
    attr=%<container>%<field>
    • <container> - identifier of a config container, such as config0, configA,...
    • <field> - name of field
    Example:
    #configA setup ndecpl s32 default=6 nbias f32.3 default=1000 nmul f32.3 default=2 #config7 measurements up va f32 decpl=%configA%ndecpl vscale=%configA%nmul vofs=%configA%nbias default=12.34

    References may even point to arrays

    Take care, that referrer and referred have the same array dimensions.
    Example:
    #configA setup decplx[5] s32 default=6 biasx[5] f32.3 default=(1000i) mulx[5] f32.3 default=(i+1) #config7 measurements up vb[5] f32 decpl=%configA%decplx[(i)] vscale=%configA%mulx[(i)] vofs=%configA%biasx[(i)] default=(12n+7)
    @target(

    Override automatic storage allocation and position all following fields starting at given target.

    This feature is typically used to define shadow fields to access the same storage area in multiple ways.
    Target may be one of these:
    fieldname - any fieldname declared already somewhere before in this same container
    $ - the current end of this container
    +1 - create a gap of 1 byte (any other number of bytes is possible as long as container's size is not exceeded)
    example
    // storage location va u8 // #0 vb u8 // #1 vc s32 // #2..5 @vb vd u16 // #1+#2 (big endian) @+1 // #3 - gap of 1 byte ve u8 // #4 @$ // go behind current end of container -> #6 @+2 // #6 - add gap of 2 byte vf u8 // #8

    TUTORIALS

    Description

    Standard library for the rapidM2M Studio ecosphere

    BASICS

    xdocs:
  • rapidM2M Introduction
  • rapidM2M API - Legacy docs
  • Pawn - Pawn Programming Manual

    • ALERTS

    alerts:
    Alerts provide a full-stack out-of-the-box mechanism to handle alarm or warning conditions. It covers
  • Generation at the device
  • Transportation to the backend
  • Presentation at the portal
  • Notification of the user via SMS, email…
  • Forwarding to frontend via API
    • If you do not use the backend's and portal's built-in alert handling, but rather do all of this in your frontend server, then it may simplify your task to use #histdataX instead of #alerts.
    To get a pre-programmed, working project, search project templates for "demo alerts"
    DDE
    Lets activate alerts with just a single line in DDE.
    #alerts // just a single command to activate alerts!
    DLO
    Whenever we see a reasonable condition we fire an alert message.
    if( measurement > (threshold+hysteresis) && !this_alert_already_active) { this_alert_already_active= true; dde_alerts_write( ALERTS_ALARM, measurement, threshold); } else if( measurement < (threshold-hysteresis) && this_alert_already_active) { this_alert_already_active= false; dde_alerts_write( ALERTS_OFF, measurement, threshold); }
    POV
    Basically there is nothing to do at the portal view. Just use the built-in elements for viewing and notification.
  • screenshot site list with pending alert
  • screenshot alert list popup (called from site list)
  • screenshot alert notification central setup
    • If you implement you individual portal view, you may add there alerts features, too.
    uapi.get( 'alerts/pending', alerts => { // show all pending alerts ...show alerts in you own portal view... }); $('button#confirm_all').click(()=>{ uapi.del( 'alerts'); // confirm all pending alerts })
    BLO
    To add your own alert handling on the backend side, use these BAPI calls.
    bapi.subscribe( 'alerts', (alert) => { ... process the new alert ... // (optional) mark alert as confirmed bapi.del( alert._id); });
    FRONTEND API
    Read and confirm alarms from your frontend server.
    fapi.get( 'SITE/alerts/pending', alerts => { // show all pending alerts ...show alerts in you own portal view... }); $('button#confirm_all').click(()=>{ fapi.del( 'SITE/alerts'); // confirm all pending alerts })

    rapidM2M M22x

    Description

    Standard library for the rapidM2M Studio ecosphere

    SYSTEM

    M22X:

    Mx_BrownOutInit(funcidx, level)

    Initialises and configures BrownOut monitoring for the voltage supply input VIN.

    funcidx : s32 - Index of the public function that should be executed if a BrownOut is detected.

    Type of the function (see TBrownOut_Callback):
    public func(level);
    level : s32 - A BrownOut should be detected if the level falls below this voltage level in [mV].
    If, following the detection of a BrownOut, the voltage exceeds this threshold again, it must remain above this threshold for at least 1sec. before a new BrownOut can be detected.
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TBrownOut_Callback(
    public func(level);
    Function to be provided by the device logic developer,
    that is called up when a BrownOut is detected on the supply voltage input VIN (registered with Mx_BrownOutInit() ).
    level : s32 - Voltage level in [mV] that caused the BrownOut to be detected
    Mx_Shutdown(powerOffTimeout=0)

    Shuts the system down.

    Device Logic execution is stopped during this process and all of the interfaces (e.g. USB; modem) are closed. The power supply can then be deactivated safely.

    A system reset is required to restore the full functionality. If the pin to activate the controller on the M22x module (ENCPU) remains "high" after shutting down the system, a reset must be executed via the pin to reset the controller (reset). Otherwise it will suffice to set the pin for activating the controller (ENCPU) back to "high".
    powerOffTimeout : s32 - Timeout (in seconds) after which an automatic system reset takes place if the power supply was not disconnected/deactivated after calling the Mx_Shutdown() function. The system reset restores the full functionality and thus restarts the execution of the Device Logic.
    returns : Terror
    OK - if successful
    Mx_GetSysValues(out values[TMx_SysValue], len=sizeof values)

    Reads the last valid operating voltage values VIN and VAUX from the system. The interval for determining these values is 1sec. and cannot be changed.

    values : TMx_SysValue - Structure for recording the measurement values
    len : s32 - Size (in cells) of the structure to store the measurement values
    returns : Terror
    >=0 - Size (in cells) of the structure used to store the measurement values
    ERROR - if one of the following errors occurs
  • Address and/or length of the values structure is invalid (outside the device logic data memory)
  • One of the measurement values is invalid
    • TMx_SysValue:

    Measurement values for the operating voltages

    VIn : s32 - Supply voltage VIN in [mV]
    VAux : s32 - Auxiliary voltage VAUX in [mV]

    HARDWARE

    M22X:

    boardref:
     
  • Product page

    • Consider that WIFI is optional and not supported by all modules!

    µINO STYLE

    → WIFINot available on all modules!digitalRead()digitalWrite()pinMode()→ DIGITAL PINspiBegin()spiTransfer()→ SPIsysRead()supplyWatch()→ SYSTEMwireBegin()wireTransfer()→ I2CserialBegin()serialWrite()→ UARTpinWatch()→ IRQledWrite()→ LED

    CLASSIC STYLE

    → WIFINot available on all modules!rM2M_GpioGet()rM2M_GpioSet()rM2M_GpioDir()→ GPIOrM2M_SpiInit()rM2M_SpiCom()→ SPIMx_GetSysValues()Mx_BrownOutInit()→ SYSTEMrM2M_I2cInit()rM2M_I2cCom()→ I2CrM2M_UartInit()rM2M_UartWrite()→ UARTrM2M_IrqInit()→ IRQMxLed_Init()MxLed_On() MxLed_Off()→ LED

    GPIO

    M22X:

    rM2M_GpioDir(gpio, dir, dirParam=-1)

    Sets the signal direction for a GPIO.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    dir : TrM2M_GPIO_DIR - Signal direction to be used for the GPIO:
    RM2M_GPIO_DISABLED - GPIO deactivated
    RM2M_GPIO_INPUT - Input
    RM2M_GPIO_OUTPUT - Output
    dirParam : RM2M_GPIO_INPUT_xxx/RM2M_GPIO_OUTPUT_xxx - Additional parameter related to configured direction (INPUT or OUTPUT) - OPTIONAL
    In case of RM2M_GPIO_INPUT
    -1Resistor deactivated
    RM2M_GPIO_INPUT_PULLDOWNPull-down resistor activated
    RM2M_GPIO_INPUT_PULLUPPull-up resistor activated
    In case of RM2M_GPIO_OUTPUT
    ValueType of outputInitial output levelInternal resistor
    -1Push-pulllast set output leveldeactivated
    RM2M_GPIO_OUTPUT_LOWPush-pull"low"deactivated
    RM2M_GPIO_OUTPUT_HIGHPush-pull"high"deactivated
    RM2M_GPIO_OUTPUT_ODOpen-drain"high"deactivated
    RM2M_GPIO_OUTPUT_OD_PULLUPOpen-drain"high"pull-up
    RM2M_GPIO_OUTPUT_OSOpen-source"low"deactivated
    RM2M_GPIO_OUTPUT_OS_PULLDOWNOpen-source"low"pull-down
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_GpioSet(gpio, level)

    Set the output level of a GPIO that was configured as an output.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    level : TrM2M_GPIO_LEVEL - Specification of the level to be issued:
    RM2M_GPIO_LOW - Output level set to "low"
    RM2M_GPIO_HIGH - Output level set to "high"
    returns : Terror
    OK - If successful
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an output
    <OK - If an error occurs, see Terror
    rM2M_GpioGet(gpio)

    Read the signal level of a GPIO that was configured as an input.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    returns : Terror
    RM2M_GPIO_LOW - For "low" at the input
    RM2M_GPIO_HIGH - For "high" at the input
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an input
    <OK - If an error occurs, see Terror
    TrM2M_GPIO_PIN

    Number of GPIO pin, ranging from 0 (= first GPIO of the device) to DP_GPIO_CNT-1

    TrM2M_GPIO_DIR: s32

    Signal direction settings of the GPIOs

    RM2M_GPIO_DISABLED = -1 - Deactivate GPIO to minimise power consumption
  • This turns off any input and output drivers
  • If the device has level shifters, those shifters having all lines disabled become powered down, too.
    • RM2M_GPIO_INPUT = 0 - Turn GPIO to input; be aware that this may drag more power than RM2M_GPIO_DISABLED
    RM2M_GPIO_OUTPUT = 1 - Turn GPIO to output
    TrM2M_GPIO_LEVEL: s32

    Signal levels of the GPIOs

    RM2M_GPIO_LOW = 0 - "low" signal level
    RM2M_GPIO_HIGH = 1 - "high" signal level
    RM2M_GPIO_INPUT_xxx: s32

    Options for Gpio direction INPUT used with rM2M_GpioDir()

    RM2M_GPIO_INPUT_PULLDOWN = 0 - activates the internal pull-down resistor of the CPU for the GPIO
    RM2M_GPIO_INPUT_PULLUP = 1 - activates the internal pull-up resistor of the CPU for the GPIO
    RM2M_GPIO_OUTPUT_xxx: s32

    Options for Gpio direction OUTPUT used with rM2M_GpioDir()

    RM2M_GPIO_OUTPUT_LOW = 0 - Push-pull output with initial level "low"
    RM2M_GPIO_OUTPUT_HIGH = 1 - Push-pull output with initial level "high"
    RM2M_GPIO_OUTPUT_OD = 2 - Open-drain output (Wired-AND) with initial level "high"
    RM2M_GPIO_OUTPUT_OD_PULLUP = 3 - Open-drain output (Wired-AND) with initial level "high" and active pull-up resistor
    RM2M_GPIO_OUTPUT_OS = 4 - Open-source output (Wired-OR) with initial level "low"
    RM2M_GPIO_OUTPUT_OS_PULLDOWN = 5 - Open-source output (Wired-OR) with initial level "low" and active pull-down resistor

    IRQ

    M22X:

    rM2M_IrqInit(irq, config, funcidx, debounce=0)

    Activates the interrupt functionality of an interruptible pin.

    irq : TrM2M_IRQ_PIN - Number of the interruptible pin, starting with 0 for the first interruptible pin of the device
    config : TrM2M_IRQ_xxx - Selection of the edge that should initiate the interrupt and activation of internal pull-up or an internal pull-down resistor:

    Selection of the edges

    RM2M_IRQ_RISING - with rising edges
    RM2M_IRQ_FALLING - with falling edges
    RM2M_IRQ_BOTH - with rising and falling edges

    Additional flags

    RM2M_IRQ_PULLUP - Activates the internal pull-up resistor of the CPU for the GPIO assigned to the interrupt
    RM2M_IRQ_PULLDOWN - Activates the internal pull-down resistor of the CPU for the GPIO assigned to the interrupt
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously. However, for each of the three modes of the edges, either an internal pull-up or an internal pull-down resistor can be activated.
    funcidx : s32 - Index of the public function that should be executed in the event of an interrupt.

    Type of the function (see TrM2M_Irq_Callback):
    public func(pinstate);
    debounce - Debounce time in ms. The interrupt is only triggered if it is pending for longer than the debounce time.
    0 = no debouncing
    returns : Terror
    OK - If successful
    ERROR_ALREADY_SUBSCRIBED - If the interrupt functionality for the relevant pin has already been initialised
    ERROR_NOT_SUPPORTED - If the pin is used elsewhere (e.g. as a GPIO)
    ERROR - If one of the following errors occurs:
  • Interrupt functionality for this pin not available
  • The function that must be executed in the event of an interrupt is not public.
    • <OK - If another error occurs, see Terror
    TrM2M_IRQ_xxx:

    Edge and resistor configuration for the rM2M_IrqInit() function

    Selection of the edges that should initiate the interrupt

    RM2M_IRQ_RISING = 0 - With rising edges
    RM2M_IRQ_FALLING = 1 - With falling edges
    RM2M_IRQ_BOTH = 2 - With rising and falling edge

    Selection of the internal resistor to be activated for the interruptible pin

    RM2M_IRQ_PULLUP = 0x04 - Activates the internal pull-up resistor
    RM2M_IRQ_PULLDOWN = 0x08 - Activates the internal pull-down resistor
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously.
    rM2M_IrqClose(irq)

    Deactivates the interrupt functionality of an interruptible pin.

    irq : TrM2M_IRQ_PIN - Number of the interruptible pin, starting with 0 for the first interruptible pin of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TrM2M_Irq_Callback(pinstate)
    public func(pinstate);
    Function to be provided by the device logic developer, that is called up in the event of an interrupt at one of the interruptible pins (registered with rM2M_IrqInit() ).
    pinstate : TrM2M_GPIO_LEVEL - Signal level at the interruptible pin
    TrM2M_IRQ_PIN

    Number of IRQ pin, ranging from 0 (= first interruptible pin of the device) to DP_IRQ_CNT-1

    UART

    M22X:

    rM2M_UartSetbuf(uart, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware for the selected UART interface with a sending and/or receiving buffer from the RAM area reserved for the device logic. When this function is called up, the system switches from the two buffers integrated in the firmware to the passed buffers.

    This function must be called up before initialising the UART interface via the rM2M_UartInit() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    rxbuf{} : u8 - Static byte array that should be used as the receive buffer
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated receiving buffer. The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as the sending buffer
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated sending buffer. The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - If successful
    ERROR - If an error occurs
    rM2M_UartInit(uart, baudrate, mode, funcidx)

    Initialises the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    baudrate : s32 - Baud rate to be used. Please observe the valid limits for the module being used.
    mode : s32 - Bitmask
    Stopbits
    RM2M_UART_1_STOPBIT = 0b000000001
    RM2M_UART_2_STOPBIT = 0b000000010
    Parity
    RM2M_UART_PARITY_NONE = 0b000000000
    RM2M_UART_PARITY_ODD = 0b000000100
    RM2M_UART_PARITY_EVEN = 0b000001000
    Databits
    RM2M_UART_7_DATABIT = 0b000000000
    RM2M_UART_8_DATABIT = 0b000010000
    Flow control
    RM2M_UART_FLOW_NONE = 0b000000000 - no flow control
    RM2M_UART_FLOW_RTSCTS = 0b001000000 - RTS/CTS handshake
    Duplex mode
    RM2M_UART_FULL_DUPLEX = 0b000000000 - rx and tx at the same time; typ. for RS232
    RM2M_UART_HALF_DUPLEX = 0b100000000 - rx/tx alteration; typ. for RS485
    funcidx : s32 - Index of the public function for the UART character receipt.

    Type of the function (see TUart_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TUart_Callback(
    public func( const data{}, len);
    Function to be provided by the device logic developer, that is called up when characters are received via the UART interface (registered with rM2M_UartInit() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    rM2M_UartClose(uart)

    Closes the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_UartWrite(uart, const data{}, len)

    Sends data via the specified UART interface.

    To read data from the UART interface, use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes if successful
    If the number of processed bytes differs from the transferred number of bytes to be sent, the rM2M_UartWrite () function must be called again. However, only the data that could not be processed during the previous call must be transferred.
    <OK - If an error occurs, see Terror
    rM2M_UartWriteStr
    rM2M_UartWriteStr(const uart, const str{})

    Sends a string via the specified UART interface.

    To read data from the UART interface use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    str : astr - ANSI string to be sent, zero terminated
    rM2M_UartWrite
    TrM2M_UART_PORT

    Number of the UART port ranging from 0 (= first UART interface of the device) to DP_UART_CNT-1

    I2C

    M22X:

    rM2M_I2cInit(i2c, clock, config)

    Initialises the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : s32 - Reserved for extensions
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the I²C interface has already been initialised
    <OK - If another error occurs, see Terror
    rM2M_I2cClose(i2c)

    Closes the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_I2cCom(i2c, addr, data{}, txlen, rxlen)

    Executes an I²C communication. Data is first of all sent and data is then received.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    addr : s32 - Address of the I²C slave (Bit7-Bit1, Bit0 unused)
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : TrM2M_I2C_ERROR
    OK - If successful
    RM2M_I2C_NACKERR - If NACK was received during transmission (e.g. incorrect device address, device not responding)
    RM2M_I2C_BUSERR - If a bus error occurs during transmission (e.g. START/STOP placed incorrectly)
    RM2M_I2C_ARBERR - If the arbitration is lost during transmission
    RM2M_I2C_USAGEFAULT - If an internal error occurs
    RM2M_I2C_SWFAULT - If an internal error occurs
    ERROR - If another error occurs, see Terror
    TrM2M_I2C_PORT

    Number of the I²C port ranging from 0 (=first I²C interface of the device) to DP_I2C_CNT-1

    TrM2M_I2C_ERROR: s32

    Error codes of the rM2M_I2cCom() function

    RM2M_I2C_NACKERR = -11 - NACK received during transmission (incorrect device address, device not responding)
    RM2M_I2C_BUSERR = -12 - Bus error during transmission (START/STOP placed incorrectly)
    RM2M_I2C_ARBERR = -13 - Arbitration lost during transmission
    RM2M_I2C_USAGEFAULT = -14 - Internal error
    RM2M_I2C_SWFAULT = -15 - Internal error

    SPI

    M22X:

    rM2M_SpiInit(spi, clock, config)

    Initialises the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : TSPI_MODE - Configuration of clock polarity and clock phase:
    Bit0: Clock polarity
    0 - idle "low"
    1 - idle "high"
    Bit1: Clock phase
    0 - Data are issued at the first edge
    1 - Data are adopted at the first edge
    It is recommended to use the predefined constants "SPI_MODE_0", "SPI_MODE_1", "SPI_MODE_2" or "SPI_MODE_3", as the resulting setting corresponds to the common definitions of SPI modes (see TSPI_MODE).
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the SPI interface has already been initialised
    <OK - If another error occurs, see Terror
    RM2M_SPI_CLKPOL - 0b00000001

    Clock polarity: Idle "high"

    Clock polarity is idle "low" if this bit is not set.
    RM2M_SPI_CLKPHA - 0b00000010

    Clock phase: Data are adopted at the first edge

    Data are issued at the first edge if this bit is not set.
    TSPI_MODE

    SPI clock polarity and phase configuration

    SPI_MODE_0 = RM2M_SPI_CLKPHA - idle low, data latch on leading edge
    SPI_MODE_1 = 0 - idle low, data shift on leading edge
    SPI_MODE_2 = RM2M_SPI_CLKPOL | RM2M_SPI_CLKPHA - idle high, data latch on leading edge
    SPI_MODE_3 = RM2M_SPI_CLKPOL - idle high, data shift on leading edge
    rM2M_SpiInit
    RM2M_SPI_CLKPOL, RM2M_SPI_CLKPHA
    rM2M_SpiClose(spi)

    Closes the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_SpiCom(spi, data{}, txlen, rxlen)

    Executes an asynchronous SPI communication. Data is first of all sent and data is then received.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : Terror
    OK - If successful
    ERROR - If one of te following errors occurs:
  • Number of bytes to be sent >255
  • Number of bytes to be received >255
    • <OK - If another error occurs, see Terror
    TrM2M_SPI_PORT

    Number of the SPI port ranging from 0 (= first SPI interface of the device) to DP_SPI_CNT-1

    LED

    M22X:

    MxLed_Init(mode)

    Initialises the open drain output to which an LED can be connected

    On M22x and M23x modules, these functions just control an open digital output, where you have to connected the LED by your own.
    mode : s32 - Selection of whether the output is controlled by the firmware or device logic
    MX_LED_MODE_INTERNAL - The output is used to indicate the operating state.
    MX_LED_MODE_SCRIPT - The state of the output can be controlled by the MxLed_On(), MxLed_Off(), MxLed_Blink(), MxLed_Flash() and MxLed_Flicker() device logic functions.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    MxLed_Close()

    Deactivates the open drain output to which an LED can be connected. The output cannot be controlled by the firmware or the device logic functions.

    returns : Terror
    OK - if successful
    MxLed_On(bool:green)

    Sets the open drain output to "low", which triggers a LED connected between the supply and output to light up.

    green : bool - true: The LED is switched on.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Off(bool:green)

    Sets the open drain output to "high", which triggers an LED connected between the supply and output to switch off.

    green : bool - true: The LED is switched off.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Blink(green)

    Enables an LED connected to the open drain output to flash (ton = 500ms , toff = 500ms ).

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED flashes until it is deliberately switched off
  • >0 : Number of times the LED should flash
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Flash(green)

    Enables an LED connected to the open drain output to briefly flash every 500ms .

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED will continue to flash at regular intervals until it is deliberately switched off
  • >0 : Number of times the LED should briefly flash at regular intervals
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Flicker(green)

    Enables an LED connected to the open drain output to flicker (ton = 94ms , toff = 31ms ).

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED flickers until it is deliberately switched off
  • >0 : Number of times the LED should flicker
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()

    WIFI

    M22X:

    TWIFI_STATE:

    WiFi states

    WIFI_STATE_OFF = 0 - Interface is inactive
    WIFI_STATE_INIT = 1 - Interface is just being initialised
    WIFI_STATE_READY = 2 - Interface is ready for operation
    WIFI_STATE_BUSY = 3 - Interface is busy
    TWIFI_EVENT:

    WiFi events

    WIFI_EVENT_SCAN = 0 - access point found during scan
    WIFI_EVENT_DEVINFO = 1 - device info available
    WIFI_EVENT_CONNECTED = 2 - connected to WiFi network (access point)
    WIFI_EVENT_DISCONNECTED = 3 - disconnected from WiFi network (access point)
    WIFI_EVENT_RSSI = 4 - RSSI value available
    WIFI_EVENT_ERROR = 5 - internal error occured -> WiFi will be powered off
    WIFI_EVENT_SOCKET_BIND = 100 - feedback for socket call WiFi_bind()
    WIFI_EVENT_SOCKET_LISTEN = 101 - feedback for socket call WiFi_listen()
    WIFI_EVENT_SOCKET_ACCEPT = 102 - feedback for incoming TCP connection
    WIFI_EVENT_SOCKET_CONNECT = 103 - feedback for socket call WiFi_sockConnect()
    WIFI_EVENT_SOCKET_RECV = 104 - TCP receive
    WIFI_EVENT_SOCKET_RECVFROM = 105 - UDP receive
    WIFI_EVENT_SOCKET_SEND = 106 - data was sent over socket (TCP)
    WIFI_EVENT_SOCKET_SENDTO = 107 - data was sent over socket (UDP)
    WIFI_EVENT_DNS_RESOLVE = 108 - feedback for DNS resolve (corresponding IP address)
    TWIFI_ERR: s8

    Internal WiFi interface error

    WIFI_ERR_UNSPECIFIED = 0 - unspecified internal error
    WIFI_ERR_INIT = 1 - error during initialization
    WIFI_ERR_AP_SCAN = 2 - error during access point scan
    WIFI_ERR_IO = 3 - error IO communication
    TWiFi_Error:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_ERROR" event.

    id : TWIFI_ERR - Error identifier
    TWiFi_DevInfo:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DEVINFO" event. It contains information regarding the WiFi module installed in the device.

    chipname{20+1} : astr - Name/title of the WiFi module
    hwrev{20+1} : astr - Hardware version of the WiFi module
    fwrev{20+1} : astr - Firmware version of the WiFi module
    mac{6} : u8 - MAC address of the WiFi module
    TWiFi_Scan:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SCAN" event. It contains information regarding a WiFi network in the receiving range.

    sec : TWIFI_SEC - Encryption method
    ch : u8 - WiFi RF channel (1-14 in 2.4 GHz frequency range)
    bssid{6} : u8 - Basic service set identification (e.g. MAC address of the access point)
    ssid{32+1} : u8 - Service Set Identifier of the WiFi network
    rssi : s8 - WiFi RSSI level [dBm]
    TWIFI_IP_CONFIG: u8

    Process for assigning the IP address configuration

    WIFI_IP_CONFIG_DHCP = 1 - IP obtained from DHCP server
    WIFI_IP_CONFIG_STATIC = 2 - static IP
    TWiFi_Connected:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_CONNECTED" event. It contains information regarding the network to which a connection was established.

    sec : TWIFI_SEC - Encryption method
    ssid{32+1} : u8 - Service Set Identifier of the WiFi network
    iptype : TWIFI_IP_CONFIG - Process for assigning the IP address configuration (STATIC or DHCP)
    ip{4} : u8 - Own IP address (IPv4)
    sn{4} : u8 - Subnet mask
    gw{4} : u8 - IP of standard gateway (IPv4)
    dns{4} : u8 - IP of DNS server (IPv4)
    TWIFI_DISCONNECT:

    Reasons for WiFi disconnection

    WIFI_DISCONNECT_OK = 0 - regular disconnection
    WIFI_DISCONNECT_SCAN_FAIL = -1 - scan failed
    WIFI_DISCONNECT_JOIN_FAIL = -2 - failed to join the BSS
    WIFI_DISCONNECT_AUTH_FAIL = -3 - failed to authenticate with the AP
    WIFI_DISCONNECT_ASSOC_FAIL = -4 - failed to associate with the AP
    WIFI_DISCONNECT_CONN_INPROGRESS = -5 - another connection request in progress
    WIFI_DISCONNECT_INTERNAL_ERR = -6 - internal driver error
    WIFI_DISCONNECT_SETTINGS = -100 - probably wrong settings (e.g. key too long/short)
    WIFI_DISCONNECT_CONNECT_FAIL = -101 - probably AP not available or wrong settings
    WIFI_DISCONNECT_AP_NOT_FOUND = -102 - AP (SSID) not found during scan
    WIFI_DISCONNECT_AP_SECURITY = -103 - AP security not supported
    WIFI_DISCONNECT_WEP_PWDLEN = -104 - PWD length for WEP is not valid
    TWiFi_Disconnected:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DISCONNECTED" event.

    cause : TWIFI_DISCONNECT - Reason for disconnection
    TWiFi_Rssi:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_RSSI" event.

    rssi : s8 - WiFi RSSI level [dBm]
    TWIFI_SEC: u8

    Encryption methods

    WIFI_SEC_INVALID = 0 - Invalid security type
    WIFI_SEC_OPEN = 1 - WiFi network is not secured
    WIFI_SEC_WPA_PSK = 2 - WiFi network is secured with WPA/WPA2 personal (PSK)
    WIFI_SEC_WEP = 3 - Security type WEP (40 or 104) OPEN OR SHARED
    WIFI_SEC_802_1X = 4 - WiFi network is secured with WPA/WPA2 Enterprise IEEE802.1x user-name/password authentication
    WiFi_Init(funcidx)

    Initialises the WiFi interface

    funcidx : s32 - Index of the public function that should be executed in the case of a WiFi event.

    Type of the function (see TWiFi_Callback):
    public func(event, connhandle, const data{}, len);
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_Callback(
    public func(event, connhandle, const data{}, len);
    Function to be provided by the device logic developer,
    that is called up when a WiFi event occurs (registered with WiFi_Init() ).
    event : TWIFI_EVENT - WiFi event that triggered the callback function being called up
    connhandle : s32 - Connection handle (only relevant for "WIFI_EVENT_SOCKET_xxx" events)
    data{} : u8 - Array that contains the data associated with the relevant event. The structure is dependent on the WiFi event that triggered the callback function being called up:
    WIFI_EVENT_SCAN - see TWiFi_Scan
    WIFI_EVENT_DEVINFO - see TWiFi_DevInfo
    WIFI_EVENT_CONNECTED - see TWiFi_Connected
    WIFI_EVENT_DISCONNECTED - see TWiFi_Disconnected
    WIFI_EVENT_RSSI - see TWiFi_Rssi
    WIFI_EVENT_ERROR - see TWiFi_Error
    WIFI_EVENT_SOCKET_BIND - see TWiFi_Bind
    WIFI_EVENT_SOCKET_LISTEN - see TWiFi_Listen
    WIFI_EVENT_SOCKET_ACCEPT - see TWiFi_Accept
    WIFI_EVENT_SOCKET_CONNECT - see TWiFi_SockConnect
    WIFI_EVENT_SOCKET_RECV - see TWiFi_Recv
    WIFI_EVENT_SOCKET_RECVFROM - see TWiFi_Recvfrom
    WIFI_EVENT_SOCKET_SEND - see TWiFi_Send
    WIFI_EVENT_SOCKET_SENDTO - see TWiFi_Send
    WIFI_EVENT_DNS_RESOLVE - see TWiFi_DNSResolve
    However, the data must be unpacked into the suitable structure using the rM2M_Pack() or rM2M_GetPackedB() function:
    new sScan[TWiFi_Scan]; /* unpack TWiFi_Scan structure */ rM2M_Pack (data, 0, sScan.sec, RM2M_PACK_GET|RM2M_PACK_U8); rM2M_Pack (data, 1, sScan.ch, RM2M_PACK_GET|RM2M_PACK_U8); rM2M_GetPackedB(data, 2, sScan.bssid, 6); rM2M_GetPackedB(data, 8, sScan.ssid, 32+1); rM2M_Pack (data, 41, sScan.rssi, RM2M_PACK_GET|RM2M_PACK_S8);
    len : s32 - Size of the data block in byte
    WiFi_Close()

    Closes the WiFi interface

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_GetState()

    Returns the current status of the WiFi interface

    returns : TWIFI_STATE - WiFi states
    WiFi_Scan()

    Starts the search for available WiFi networks on all channels supported by the installed WiFi module.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_Connect()

    Establishes a connection to an access point.

    The SSID of the network being used and the required configuration must be written in the "REG_APP_FLASH" registration memory block before calling up this function. The rM2M_RegSetString() function can be used for this purpose.
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_Disconnect()

    Disconnects the current connection to the access point.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_GetRSSI()

    Starts determining the WiFi RSSI level [dBm].

    The device must be connected to an access point during this process. If the measurement is completed, the "WIFI_EVENT_RSSI" event is triggered by the system and the determined WiFi RSSI level [dBm] can be evaluated with the help of the callback function that is to be provided by the device logic developer (see TWiFi_Callback).
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_APCfg:

    Configuration for an access point

    sec : TWIFI_SEC - Encryption method
    ssid{32+1} : u8 - Service set identifier of the WiFi network that should be made available
    ssidHide : s32 - Specifies whether the network SSID should be hidden
    0 - SSID is visible
    1 - SSID should be hidden
    pwd{64+1} : astr - Authentication password (dependent on the encryption method)
    WIFI_SEC_WPA_PSK requires at least 9 characters!
    rfchnl : s32 - WiFi RF channel that should be used
    ip{4} : u8 - IP address of the access point (IPv4)
    WiFi_APInit(cfg[TWiFi_APCfg], len=sizeof cfg)

    Configures and activates the device in access point mode

    cfg : TWiFi_APCfg - Structure that contains the configuration for the access point
    len : s32 - Size (in cells) of the structure that contains the configuration for the access point
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWIFI_AF: u16

    Address families for socket connections

    WIFI_AF_INET = 2 - Address family used for IPv4
    TWIFI_SOCK_TYPE:

    Type of socket

    WIFI_SOCK_STREAM = 1 - reliable connection-oriented stream connection, i.e. TCP
    WIFI_SOCK_DGRAM = 2 - unreliable connectionless datagram connection, i.e. UDP
    Tsockaddr_in:

    Socket address information for IPv4 addresses. Either contains

  • Address family, port and IP address which should be assigned to a socket using the BIND operation,
  • Address family, port and IP address that should be used to establish a connection to a server using the CONNECT operation or
  • Address family, port and IP address of the server to which the data should be sent using via the SENDTO operation.
    • sin_family : TWIFI_AF - The address family that should be used
    sin_port : s32 - Port that should be used
    sin_addr[4] : s32
  • Server: IP address from which requests are accepted. Can be set to "0.0.0.0" to accept all IP addresses.
  • Client TCP: IP address of the server with which a connection should be established.
  • Client UDP: IP address of the server to which the data should be sent.
    • TWIFI_SOCK_ERR:

    Error codes for socket operations

    Error codes -15, -18, -20 intentionally omitted!
    WIFI_SOCK_ERR_INVALID_ADDRESS = -11
    Socket address is invalid.
    The socket operation cannot be completed successfully without specifying a specific address. For example: bind is called without specifying a port number
    WIFI_SOCK_ERR_ADDR_IN_USE = -12
    Socket operation cannot bind on the given address.
    With socket operations, only one IP address per socket is permitted. Any attempt for a new socket to bind with an IP address already bound to another open socket, will return this error code. States indicating that bind operation failed.
    WIFI_SOCK_ERR_MAX_TCP_SOCK = -13 - Exceeded the maximum number of TCP sockets
    WIFI_SOCK_ERR_MAX_UDP_SOCK = -14 - Exceeded the maximum number of UDP sockets
    WIFI_SOCK_ERR_INVALID_ARG = -16 - An invalid argument is passed to a function.
    WIFI_SOCK_ERR_MAX_LISTEN_SOCK = -17 - Exceeded the maximum number of TCP passive listening sockets
    WIFI_SOCK_ERR_INVALID = -19 - The requested socket operation is not valid in the current socket state.
    WIFI_SOCK_ERR_ADDR_IS_REQUIRED = -21 - Destination address is required.
    WIFI_SOCK_ERR_CONN_ABORTED = -22 - The socket is closed by the peer. The local socket is also closed.
    WIFI_SOCK_ERR_TIMEOUT = -23 - The socket pending operation has timed out
    WIFI_SOCK_ERR_BUFFER_FULL = -24 - No buffer space available to be used for the requested socket operation.
    WIFI_SOCK_ERR_RECV_BUF_FULL = -100 - Not enough space within recv buffer
    WIFI_SOCK_ERR_NO_MEMCTX = -101 - Memory context not available -> operation not possible
    WiFi_socket(domain, type, flags=0)

    Generates a socket. If a socket could be generated, it can be used immediately (synchronous operation).

    domain : TWIFI_AF - Address family used for the socket connection
    type : TWIFI_SOCK_TYPE - Type of generated socket ("WIFI_SOCK_STREAM" for TCP, "WIFI_SOCK_DGRAM" for UDP)
    flags : s32 - Reserved for extensions
    returns : Terror
    > = 0 - Socket, if a socket could be generated
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Bind:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_BIND" event.

    result : s8 - Result code of the BIND operation.
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_bind(socket, sockaddr[Tsockaddr_in])

    Assigns the address information (address family, port and IP address) to a socket (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_BIND" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket to which the address information should be assigned. The socket must be generated using the WiFi_socket() function beforehand.
    sockaddr : [Tsockaddr_in] - Structure that contains the address information
    returns : Terror
    OK - if the BIND operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Listen:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_LISTEN" event.

    result : s8 - Resultcode for LISTEN operation
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    TWiFi_Accept:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_ACCEPT" event. It contains information regarding a socket connection accepted by the system (WiFi module and firmware).

    socket : s8
    > = 0 - Socket via which the connection to the receiver is established
    < OK - socket error of type TWIFI_SOCK_ERR
    family : TWIFI_AF - Address family used for the socket connection
    port : u16 - Port via which the connection to the receiver is established
    addr{4} : u8 - IP address of the receiver
    WiFi_listen(socket)

    Prepares the socket to react to incoming connections (only necessary for connection-oriented stream connection, e.g. TCP server) (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_LISTEN" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer. If the LISTEN operation could be completed successfully, then the socket is ready for incoming connections. In the event of an incoming connection, the "WIFI_EVENT_SOCKET_ACCEPT" event is triggered, which must be evaluated by the callback function that is to be provided by the device logic developer.

    Before calling up this function, the address information must be assigned to the socket using the WiFi_bind() function.
    socket : s32 - Socket that should be prepared to react to incoming connections
    returns : Terror
    OK - if the LISTEN operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_SockConnect:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_CONNECT" event.

    result : s8 - Result code of the CONNECT operation
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_sockConnect(socket, remoteaddr[Tsockaddr_in])

    Establishes a TCP connection to a server (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_CONNECT" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket that should be used for the TCP connection to the server. The socket must be generated using the WiFi_socket() function beforehand.
    remoteaddr : Tsockaddr_in - Structure that contains the address information (address family, port and IP address)
    returns : Terror
    OK - OK if the CONNECT operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Recv:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_RECV" event. It either contains the number of received bytes or specifies the error that has occurred.

    In the case of an error, the socket must be closed using the WiFi_sockClose() function.
    received : s16
    >0 - Number of received bytes
    0 - Socket closed
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_recv(socket, buf{}, len, timeout=0)

    Function to receive data via a TCP socket (asynchronous operation). Once data is received, the "WIFI_EVENT_SOCKET_RECV" event is triggered and the received data must be processed by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be received
    buf{} : u8 - Buffer to store received data (must be public)
    len : s32 - Size (in bytes) of the buffer to store the data to be received
    timeout : s32 - Timeout for receiving data in [ms]. 0...no timeout
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Recvfrom:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_RECVFROM" event. It contains information regarding data received when using a connectionless network protocol (e.g. UDP).

    In the case of an error, the socket must be closed using the WiFi_sockClose() function.
    received : s16
    >0 - Number of received bytes
    0 - Socket closed
    < OK - socket error of type TWIFI_SOCK_ERR
    Socket must be closed using WiFi_sockClose() if error occured!
    family : TWIFI_AF - Address family used
    port : u16 - Port via which the data was received
    addr{4} : u8 - IP address of the sender of the data
    WiFi_recvfrom(socket, buf{}, len, timeout=0)

    Function to receive data via a UDP socket (asynchronous operation). Once data is received, the "WIFI_EVENT_SOCKET_RECVFROM" event is triggered and the received data must be processed by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be received
    buf{} : u8 - Buffer to store received data (must be public)
    len : s32 - Size (in bytes) of the buffer to store the data to be received
    timeout : s32 - Timeout for receiving data in [ms]. 0...no timeout
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sockMemCtx(socket, rxbuf{}, rxbuflen)

    Provides the firmware with a buffer from the RAM area reserved for the device logic for the specified socket. The transferred memory is used to internally process data in connection with the specified socket. The buffer should be assigned using this function immediately after generating the socket. As long as the socket has not been closed using the WiFi_sockClose() function, the transferred buffer may not be accessed via the device logic.

    socket : s32 - Socket for which the buffer should be made available
    rxbuf{} : u8 - Byte array that should be used as the receive buffer
    rxbuflen : s32 - Size of the receive buffer in byte
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_Send:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_SEND" (TCP) and "WIFI_EVENT_SOCKET_SENDTO (UDP)" events.

    sent : s16
    >0 - Number of sent bytes
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_send(socket, buf{}, len)

    Function to send data via a TCP socket (asynchronous operation). Once the data has been sent, the "WIFI_EVENT_SOCKET_SEND" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be sent
    buf{} : u8 - Buffer that contains the data to be sent
    The buffer must be "public". The content is changed by the send function as part of being processed.
    len : s32 - Number of bytes to be sent (max. 1400)
    returns : Terror
    >0 - Number of bytes accepted for processing if the SEND operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sendto(socket, buf{}, len, remoteaddr[Tsockaddr_in])

    Function to send data via a UDP socket (asynchronous operation). Once the data has been sent, the "WIFI_EVENT_SOCKET_SENDTO" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket - Socket via which the data should be sent
    buf{} : u8 - Buffer that contains the data to be sent
    The buffer must be "public". The content is changed by the send function as part of being processed.
    len : s32 - Number of bytes to be sent (max. 1400)
    remoteaddr : Tsockaddr_in - Structure that contains the address information (address family, port and IP address)
    returns : Terror
    >0 - Number of bytes accepted for processing if the SENDTO operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sockClose(socket)

    Closes the socket and releases all of the resources assigned to the socket (synchronous operation)

    All of the outstanding messages (to be sent or received) are discarded.
    socket : s32 - Socket that should be closed
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_DNSResolve:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DNS_RESOLVE" event.

    ip{4} : u8 - Resolved IPv4 address or 0.0.0.0 in the event of an error
    WiFi_gethostbyname(const hostname{})

    Asynchronous function to resolve a host name (e.g. URL) into a host IP address using the domain name system (DNS). The IP address of a DNS server must be saved to be able to execute the operation correctly. This address must either be obtained from the access point when using DHCP or must be written in the "REG_APP_FLASH" registration memory block. The rM2M_RegSetString() function can be used for this purpose. If the resolution of the host name is completed (OK or NOT OK), the "WIFI_EVENT_DNS_RESOLVE" event is triggered by the system and the determined IP address can continue to be processed with the help of the callback function that is to be provided by the device logic developer (see TWiFi_Callback).

    hostname{} : astr - Host name (e.g. URL) for which the associated IP address should be determined
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs

    rapidM2M M23x

    Description

    Standard library for the rapidM2M Studio ecosphere

    HARDWARE

    M23X:

    boardref:
    +++ PRELIMINARY INFORMATION - may change without further notice +++
     
  • Product page

    • Consider that WIFI is optional and not supported by all modules!
    cheatsheet:

    CLASSIC STYLE

    → WIFINot available on all modules!rM2M_GpioGet()rM2M_GpioSet()rM2M_GpioDir()→ GPIOrM2M_SpiInit()rM2M_SpiCom()→ SPIMx_GetSysValues()Mx_BrownOutInit()→ SYSTEMrM2M_I2cInit()rM2M_I2cCom()→ I2CrM2M_UartInit()rM2M_UartWrite()→ UARTrM2M_IrqInit()→ IRQMxLed_Init()MxLed_On() MxLed_Off()→ LED

    SYSTEM

    M23X:

    Mx_Shutdown(powerOffTimeout=0)

    Shuts the system down.

    Device Logic execution is stopped during this process and all of the interfaces (e.g. USB; modem) are closed. The power supply can then be deactivated safely.

    A system reset is required to restore the full functionality. If the pin to activate the controller on the M22x module (ENCPU) remains "high" after shutting down the system, a reset must be executed via the pin to reset the controller (reset). Otherwise it will suffice to set the pin for activating the controller (ENCPU) back to "high".
    powerOffTimeout : s32 - Timeout (in seconds) after which an automatic system reset takes place if the power supply was not disconnected/deactivated after calling the Mx_Shutdown() function. The system reset restores the full functionality and thus restarts the execution of the Device Logic.
    returns : Terror
    OK - if successful
    Mx_GetSysValues(out values[TMx_SysValue], len=sizeof values)

    Reads the last valid operating voltage values VIN and VAUX from the system. The interval for determining these values is 1sec. and cannot be changed.

    values : TMx_SysValue - Structure for recording the measurement values
    len : s32 - Size (in cells) of the structure to store the measurement values
    returns : Terror
    >=0 - Size (in cells) of the structure used to store the measurement values
    ERROR - if one of the following errors occurs
  • Address and/or length of the values structure is invalid (outside the device logic data memory)
  • One of the measurement values is invalid
    • TMx_SysValue:

    Measurement values for the operating voltages

    VIn : s32 - Supply voltage VIN in [mV]
    VAux : s32 - Auxiliary voltage VAUX in [mV]

    GPIO

    M23X:

    rM2M_GpioDir(gpio, dir, dirParam=-1)

    Sets the signal direction for a GPIO.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    dir : TrM2M_GPIO_DIR - Signal direction to be used for the GPIO:
    RM2M_GPIO_DISABLED - GPIO deactivated
    RM2M_GPIO_INPUT - Input
    RM2M_GPIO_OUTPUT - Output
    dirParam : RM2M_GPIO_INPUT_xxx/RM2M_GPIO_OUTPUT_xxx - Additional parameter related to configured direction (INPUT or OUTPUT) - OPTIONAL
    In case of RM2M_GPIO_INPUT
    -1Resistor deactivated
    RM2M_GPIO_INPUT_PULLDOWNPull-down resistor activated
    RM2M_GPIO_INPUT_PULLUPPull-up resistor activated
    In case of RM2M_GPIO_OUTPUT
    ValueType of outputInitial output levelInternal resistor
    -1Push-pulllast set output leveldeactivated
    RM2M_GPIO_OUTPUT_LOWPush-pull"low"deactivated
    RM2M_GPIO_OUTPUT_HIGHPush-pull"high"deactivated
    RM2M_GPIO_OUTPUT_ODOpen-drain"high"deactivated
    RM2M_GPIO_OUTPUT_OD_PULLUPOpen-drain"high"pull-up
    RM2M_GPIO_OUTPUT_OSOpen-source"low"deactivated
    RM2M_GPIO_OUTPUT_OS_PULLDOWNOpen-source"low"pull-down
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_GpioSet(gpio, level)

    Set the output level of a GPIO that was configured as an output.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    level : TrM2M_GPIO_LEVEL - Specification of the level to be issued:
    RM2M_GPIO_LOW - Output level set to "low"
    RM2M_GPIO_HIGH - Output level set to "high"
    returns : Terror
    OK - If successful
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an output
    <OK - If an error occurs, see Terror
    rM2M_GpioGet(gpio)

    Read the signal level of a GPIO that was configured as an input.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    returns : Terror
    RM2M_GPIO_LOW - For "low" at the input
    RM2M_GPIO_HIGH - For "high" at the input
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an input
    <OK - If an error occurs, see Terror
    TrM2M_GPIO_PIN

    Number of GPIO pin, ranging from 0 (= first GPIO of the device) to DP_GPIO_CNT-1

    TrM2M_GPIO_DIR: s32

    Signal direction settings of the GPIOs

    RM2M_GPIO_DISABLED = -1 - Deactivate GPIO to minimise power consumption
  • This turns off any input and output drivers
  • If the device has level shifters, those shifters having all lines disabled become powered down, too.
    • RM2M_GPIO_INPUT = 0 - Turn GPIO to input; be aware that this may drag more power than RM2M_GPIO_DISABLED
    RM2M_GPIO_OUTPUT = 1 - Turn GPIO to output
    TrM2M_GPIO_LEVEL: s32

    Signal levels of the GPIOs

    RM2M_GPIO_LOW = 0 - "low" signal level
    RM2M_GPIO_HIGH = 1 - "high" signal level
    RM2M_GPIO_INPUT_xxx: s32

    Options for Gpio direction INPUT used with rM2M_GpioDir()

    RM2M_GPIO_INPUT_PULLDOWN = 0 - activates the internal pull-down resistor of the CPU for the GPIO
    RM2M_GPIO_INPUT_PULLUP = 1 - activates the internal pull-up resistor of the CPU for the GPIO
    RM2M_GPIO_OUTPUT_xxx: s32

    Options for Gpio direction OUTPUT used with rM2M_GpioDir()

    RM2M_GPIO_OUTPUT_LOW = 0 - Push-pull output with initial level "low"
    RM2M_GPIO_OUTPUT_HIGH = 1 - Push-pull output with initial level "high"
    RM2M_GPIO_OUTPUT_OD = 2 - Open-drain output (Wired-AND) with initial level "high"
    RM2M_GPIO_OUTPUT_OD_PULLUP = 3 - Open-drain output (Wired-AND) with initial level "high" and active pull-up resistor
    RM2M_GPIO_OUTPUT_OS = 4 - Open-source output (Wired-OR) with initial level "low"
    RM2M_GPIO_OUTPUT_OS_PULLDOWN = 5 - Open-source output (Wired-OR) with initial level "low" and active pull-down resistor

    IRQ

    M23X:

    rM2M_IrqInit(irq, config, funcidx, debounce=0)

    Activates the interrupt functionality of an interruptible pin.

    irq : TrM2M_IRQ_PIN - Number of the interruptible pin, starting with 0 for the first interruptible pin of the device
    config : TrM2M_IRQ_xxx - Selection of the edge that should initiate the interrupt and activation of internal pull-up or an internal pull-down resistor:

    Selection of the edges

    RM2M_IRQ_RISING - with rising edges
    RM2M_IRQ_FALLING - with falling edges
    RM2M_IRQ_BOTH - with rising and falling edges

    Additional flags

    RM2M_IRQ_PULLUP - Activates the internal pull-up resistor of the CPU for the GPIO assigned to the interrupt
    RM2M_IRQ_PULLDOWN - Activates the internal pull-down resistor of the CPU for the GPIO assigned to the interrupt
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously. However, for each of the three modes of the edges, either an internal pull-up or an internal pull-down resistor can be activated.
    funcidx : s32 - Index of the public function that should be executed in the event of an interrupt.

    Type of the function (see TrM2M_Irq_Callback):
    public func(pinstate);
    debounce - Debounce time in ms. The interrupt is only triggered if it is pending for longer than the debounce time.
    0 = no debouncing
    returns : Terror
    OK - If successful
    ERROR_ALREADY_SUBSCRIBED - If the interrupt functionality for the relevant pin has already been initialised
    ERROR_NOT_SUPPORTED - If the pin is used elsewhere (e.g. as a GPIO)
    ERROR - If one of the following errors occurs:
  • Interrupt functionality for this pin not available
  • The function that must be executed in the event of an interrupt is not public.
    • <OK - If another error occurs, see Terror
    TrM2M_IRQ_xxx:

    Edge and resistor configuration for the rM2M_IrqInit() function

    Selection of the edges that should initiate the interrupt

    RM2M_IRQ_RISING = 0 - With rising edges
    RM2M_IRQ_FALLING = 1 - With falling edges
    RM2M_IRQ_BOTH = 2 - With rising and falling edge

    Selection of the internal resistor to be activated for the interruptible pin

    RM2M_IRQ_PULLUP = 0x04 - Activates the internal pull-up resistor
    RM2M_IRQ_PULLDOWN = 0x08 - Activates the internal pull-down resistor
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously.
    rM2M_IrqClose(irq)

    Deactivates the interrupt functionality of an interruptible pin.

    irq : TrM2M_IRQ_PIN - Number of the interruptible pin, starting with 0 for the first interruptible pin of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TrM2M_Irq_Callback(pinstate)
    public func(pinstate);
    Function to be provided by the device logic developer, that is called up in the event of an interrupt at one of the interruptible pins (registered with rM2M_IrqInit() ).
    pinstate : TrM2M_GPIO_LEVEL - Signal level at the interruptible pin
    TrM2M_IRQ_PIN

    Number of IRQ pin, ranging from 0 (= first interruptible pin of the device) to DP_IRQ_CNT-1

    UART

    M23X:

    rM2M_UartSetbuf(uart, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware for the selected UART interface with a sending and/or receiving buffer from the RAM area reserved for the device logic. When this function is called up, the system switches from the two buffers integrated in the firmware to the passed buffers.

    This function must be called up before initialising the UART interface via the rM2M_UartInit() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    rxbuf{} : u8 - Static byte array that should be used as the receive buffer
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated receiving buffer. The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as the sending buffer
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated sending buffer. The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - If successful
    ERROR - If an error occurs
    rM2M_UartInit(uart, baudrate, mode, funcidx)

    Initialises the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    baudrate : s32 - Baud rate to be used. Please observe the valid limits for the module being used.
    mode : s32 - Bitmask
    Stopbits
    RM2M_UART_1_STOPBIT = 0b000000001
    RM2M_UART_2_STOPBIT = 0b000000010
    Parity
    RM2M_UART_PARITY_NONE = 0b000000000
    RM2M_UART_PARITY_ODD = 0b000000100
    RM2M_UART_PARITY_EVEN = 0b000001000
    Databits
    RM2M_UART_7_DATABIT = 0b000000000
    RM2M_UART_8_DATABIT = 0b000010000
    Flow control
    RM2M_UART_FLOW_NONE = 0b000000000 - no flow control
    RM2M_UART_FLOW_RTSCTS = 0b001000000 - RTS/CTS handshake
    Duplex mode
    RM2M_UART_FULL_DUPLEX = 0b000000000 - rx and tx at the same time; typ. for RS232
    RM2M_UART_HALF_DUPLEX = 0b100000000 - rx/tx alteration; typ. for RS485
    funcidx : s32 - Index of the public function for the UART character receipt.

    Type of the function (see TUart_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    TUart_Callback(
    public func( const data{}, len);
    Function to be provided by the device logic developer, that is called up when characters are received via the UART interface (registered with rM2M_UartInit() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    rM2M_UartClose(uart)

    Closes the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_UartWrite(uart, const data{}, len)

    Sends data via the specified UART interface.

    To read data from the UART interface, use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes if successful
    If the number of processed bytes differs from the transferred number of bytes to be sent, the rM2M_UartWrite () function must be called again. However, only the data that could not be processed during the previous call must be transferred.
    <OK - If an error occurs, see Terror
    rM2M_UartWriteStr
    rM2M_UartWriteStr(const uart, const str{})

    Sends a string via the specified UART interface.

    To read data from the UART interface use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    str : astr - ANSI string to be sent, zero terminated
    rM2M_UartWrite
    TrM2M_UART_PORT

    Number of the UART port ranging from 0 (= first UART interface of the device) to DP_UART_CNT-1

    I2C

    M23X:

    rM2M_I2cInit(i2c, clock, config)

    Initialises the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : s32 - Reserved for extensions
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the I²C interface has already been initialised
    <OK - If another error occurs, see Terror
    rM2M_I2cClose(i2c)

    Closes the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_I2cCom(i2c, addr, data{}, txlen, rxlen)

    Executes an I²C communication. Data is first of all sent and data is then received.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    addr : s32 - Address of the I²C slave (Bit7-Bit1, Bit0 unused)
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : TrM2M_I2C_ERROR
    OK - If successful
    RM2M_I2C_NACKERR - If NACK was received during transmission (e.g. incorrect device address, device not responding)
    RM2M_I2C_BUSERR - If a bus error occurs during transmission (e.g. START/STOP placed incorrectly)
    RM2M_I2C_ARBERR - If the arbitration is lost during transmission
    RM2M_I2C_USAGEFAULT - If an internal error occurs
    RM2M_I2C_SWFAULT - If an internal error occurs
    ERROR - If another error occurs, see Terror
    TrM2M_I2C_PORT

    Number of the I²C port ranging from 0 (=first I²C interface of the device) to DP_I2C_CNT-1

    TrM2M_I2C_ERROR: s32

    Error codes of the rM2M_I2cCom() function

    RM2M_I2C_NACKERR = -11 - NACK received during transmission (incorrect device address, device not responding)
    RM2M_I2C_BUSERR = -12 - Bus error during transmission (START/STOP placed incorrectly)
    RM2M_I2C_ARBERR = -13 - Arbitration lost during transmission
    RM2M_I2C_USAGEFAULT = -14 - Internal error
    RM2M_I2C_SWFAULT = -15 - Internal error

    SPI

    M23X:

    rM2M_SpiInit(spi, clock, config)

    Initialises the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : TSPI_MODE - Configuration of clock polarity and clock phase:
    Bit0: Clock polarity
    0 - idle "low"
    1 - idle "high"
    Bit1: Clock phase
    0 - Data are issued at the first edge
    1 - Data are adopted at the first edge
    It is recommended to use the predefined constants "SPI_MODE_0", "SPI_MODE_1", "SPI_MODE_2" or "SPI_MODE_3", as the resulting setting corresponds to the common definitions of SPI modes (see TSPI_MODE).
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the SPI interface has already been initialised
    <OK - If another error occurs, see Terror
    RM2M_SPI_CLKPOL - 0b00000001

    Clock polarity: Idle "high"

    Clock polarity is idle "low" if this bit is not set.
    RM2M_SPI_CLKPHA - 0b00000010

    Clock phase: Data are adopted at the first edge

    Data are issued at the first edge if this bit is not set.
    TSPI_MODE

    SPI clock polarity and phase configuration

    SPI_MODE_0 = RM2M_SPI_CLKPHA - idle low, data latch on leading edge
    SPI_MODE_1 = 0 - idle low, data shift on leading edge
    SPI_MODE_2 = RM2M_SPI_CLKPOL | RM2M_SPI_CLKPHA - idle high, data latch on leading edge
    SPI_MODE_3 = RM2M_SPI_CLKPOL - idle high, data shift on leading edge
    rM2M_SpiInit
    RM2M_SPI_CLKPOL, RM2M_SPI_CLKPHA
    rM2M_SpiClose(spi)

    Closes the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_SpiCom(spi, data{}, txlen, rxlen)

    Executes an asynchronous SPI communication. Data is first of all sent and data is then received.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : Terror
    OK - If successful
    ERROR - If one of te following errors occurs:
  • Number of bytes to be sent >255
  • Number of bytes to be received >255
    • <OK - If another error occurs, see Terror
    TrM2M_SPI_PORT

    Number of the SPI port ranging from 0 (= first SPI interface of the device) to DP_SPI_CNT-1

    LED

    M23X:

    MxLed_Init(mode)

    Initialises the open drain output to which an LED can be connected

    On M22x and M23x modules, these functions just control an open digital output, where you have to connected the LED by your own.
    mode : s32 - Selection of whether the output is controlled by the firmware or device logic
    MX_LED_MODE_INTERNAL - The output is used to indicate the operating state.
    MX_LED_MODE_SCRIPT - The state of the output can be controlled by the MxLed_On(), MxLed_Off(), MxLed_Blink(), MxLed_Flash() and MxLed_Flicker() device logic functions.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    MxLed_Close()

    Deactivates the open drain output to which an LED can be connected. The output cannot be controlled by the firmware or the device logic functions.

    returns : Terror
    OK - if successful
    MxLed_On(bool:green)

    Sets the open drain output to "low", which triggers a LED connected between the supply and output to light up.

    green : bool - true: The LED is switched on.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Off(bool:green)

    Sets the open drain output to "high", which triggers an LED connected between the supply and output to switch off.

    green : bool - true: The LED is switched off.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Blink(green)

    Enables an LED connected to the open drain output to flash (ton = 500ms , toff = 500ms ).

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED flashes until it is deliberately switched off
  • >0 : Number of times the LED should flash
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Flash(green)

    Enables an LED connected to the open drain output to briefly flash every 500ms .

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED will continue to flash at regular intervals until it is deliberately switched off
  • >0 : Number of times the LED should briefly flash at regular intervals
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()
    MxLed_Flicker(green)

    Enables an LED connected to the open drain output to flicker (ton = 94ms , toff = 31ms ).

    green : s32
  • -1 : The LED remains switched off
  • 0 : The LED flickers until it is deliberately switched off
  • >0 : Number of times the LED should flicker
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    requires MxLed_Init()

    WIFI

    M23X:

    TWIFI_STATE:

    WiFi states

    WIFI_STATE_OFF = 0 - Interface is inactive
    WIFI_STATE_INIT = 1 - Interface is just being initialised
    WIFI_STATE_READY = 2 - Interface is ready for operation
    WIFI_STATE_BUSY = 3 - Interface is busy
    TWIFI_EVENT:

    WiFi events

    WIFI_EVENT_SCAN = 0 - access point found during scan
    WIFI_EVENT_DEVINFO = 1 - device info available
    WIFI_EVENT_CONNECTED = 2 - connected to WiFi network (access point)
    WIFI_EVENT_DISCONNECTED = 3 - disconnected from WiFi network (access point)
    WIFI_EVENT_RSSI = 4 - RSSI value available
    WIFI_EVENT_ERROR = 5 - internal error occured -> WiFi will be powered off
    WIFI_EVENT_SOCKET_BIND = 100 - feedback for socket call WiFi_bind()
    WIFI_EVENT_SOCKET_LISTEN = 101 - feedback for socket call WiFi_listen()
    WIFI_EVENT_SOCKET_ACCEPT = 102 - feedback for incoming TCP connection
    WIFI_EVENT_SOCKET_CONNECT = 103 - feedback for socket call WiFi_sockConnect()
    WIFI_EVENT_SOCKET_RECV = 104 - TCP receive
    WIFI_EVENT_SOCKET_RECVFROM = 105 - UDP receive
    WIFI_EVENT_SOCKET_SEND = 106 - data was sent over socket (TCP)
    WIFI_EVENT_SOCKET_SENDTO = 107 - data was sent over socket (UDP)
    WIFI_EVENT_DNS_RESOLVE = 108 - feedback for DNS resolve (corresponding IP address)
    TWIFI_ERR: s8

    Internal WiFi interface error

    WIFI_ERR_UNSPECIFIED = 0 - unspecified internal error
    WIFI_ERR_INIT = 1 - error during initialization
    WIFI_ERR_AP_SCAN = 2 - error during access point scan
    WIFI_ERR_IO = 3 - error IO communication
    TWiFi_Error:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_ERROR" event.

    id : TWIFI_ERR - Error identifier
    TWiFi_DevInfo:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DEVINFO" event. It contains information regarding the WiFi module installed in the device.

    chipname{20+1} : astr - Name/title of the WiFi module
    hwrev{20+1} : astr - Hardware version of the WiFi module
    fwrev{20+1} : astr - Firmware version of the WiFi module
    mac{6} : u8 - MAC address of the WiFi module
    TWiFi_Scan:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SCAN" event. It contains information regarding a WiFi network in the receiving range.

    sec : TWIFI_SEC - Encryption method
    ch : u8 - WiFi RF channel (1-14 in 2.4 GHz frequency range)
    bssid{6} : u8 - Basic service set identification (e.g. MAC address of the access point)
    ssid{32+1} : u8 - Service Set Identifier of the WiFi network
    rssi : s8 - WiFi RSSI level [dBm]
    TWIFI_IP_CONFIG: u8

    Process for assigning the IP address configuration

    WIFI_IP_CONFIG_DHCP = 1 - IP obtained from DHCP server
    WIFI_IP_CONFIG_STATIC = 2 - static IP
    TWiFi_Connected:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_CONNECTED" event. It contains information regarding the network to which a connection was established.

    sec : TWIFI_SEC - Encryption method
    ssid{32+1} : u8 - Service Set Identifier of the WiFi network
    iptype : TWIFI_IP_CONFIG - Process for assigning the IP address configuration (STATIC or DHCP)
    ip{4} : u8 - Own IP address (IPv4)
    sn{4} : u8 - Subnet mask
    gw{4} : u8 - IP of standard gateway (IPv4)
    dns{4} : u8 - IP of DNS server (IPv4)
    TWIFI_DISCONNECT:

    Reasons for WiFi disconnection

    WIFI_DISCONNECT_OK = 0 - regular disconnection
    WIFI_DISCONNECT_SCAN_FAIL = -1 - scan failed
    WIFI_DISCONNECT_JOIN_FAIL = -2 - failed to join the BSS
    WIFI_DISCONNECT_AUTH_FAIL = -3 - failed to authenticate with the AP
    WIFI_DISCONNECT_ASSOC_FAIL = -4 - failed to associate with the AP
    WIFI_DISCONNECT_CONN_INPROGRESS = -5 - another connection request in progress
    WIFI_DISCONNECT_INTERNAL_ERR = -6 - internal driver error
    WIFI_DISCONNECT_SETTINGS = -100 - probably wrong settings (e.g. key too long/short)
    WIFI_DISCONNECT_CONNECT_FAIL = -101 - probably AP not available or wrong settings
    WIFI_DISCONNECT_AP_NOT_FOUND = -102 - AP (SSID) not found during scan
    WIFI_DISCONNECT_AP_SECURITY = -103 - AP security not supported
    WIFI_DISCONNECT_WEP_PWDLEN = -104 - PWD length for WEP is not valid
    TWiFi_Disconnected:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DISCONNECTED" event.

    cause : TWIFI_DISCONNECT - Reason for disconnection
    TWiFi_Rssi:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_RSSI" event.

    rssi : s8 - WiFi RSSI level [dBm]
    TWIFI_SEC: u8

    Encryption methods

    WIFI_SEC_INVALID = 0 - Invalid security type
    WIFI_SEC_OPEN = 1 - WiFi network is not secured
    WIFI_SEC_WPA_PSK = 2 - WiFi network is secured with WPA/WPA2 personal (PSK)
    WIFI_SEC_WEP = 3 - Security type WEP (40 or 104) OPEN OR SHARED
    WIFI_SEC_802_1X = 4 - WiFi network is secured with WPA/WPA2 Enterprise IEEE802.1x user-name/password authentication
    WiFi_Init(funcidx)

    Initialises the WiFi interface

    funcidx : s32 - Index of the public function that should be executed in the case of a WiFi event.

    Type of the function (see TWiFi_Callback):
    public func(event, connhandle, const data{}, len);
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_Callback(
    public func(event, connhandle, const data{}, len);
    Function to be provided by the device logic developer,
    that is called up when a WiFi event occurs (registered with WiFi_Init() ).
    event : TWIFI_EVENT - WiFi event that triggered the callback function being called up
    connhandle : s32 - Connection handle (only relevant for "WIFI_EVENT_SOCKET_xxx" events)
    data{} : u8 - Array that contains the data associated with the relevant event. The structure is dependent on the WiFi event that triggered the callback function being called up:
    WIFI_EVENT_SCAN - see TWiFi_Scan
    WIFI_EVENT_DEVINFO - see TWiFi_DevInfo
    WIFI_EVENT_CONNECTED - see TWiFi_Connected
    WIFI_EVENT_DISCONNECTED - see TWiFi_Disconnected
    WIFI_EVENT_RSSI - see TWiFi_Rssi
    WIFI_EVENT_ERROR - see TWiFi_Error
    WIFI_EVENT_SOCKET_BIND - see TWiFi_Bind
    WIFI_EVENT_SOCKET_LISTEN - see TWiFi_Listen
    WIFI_EVENT_SOCKET_ACCEPT - see TWiFi_Accept
    WIFI_EVENT_SOCKET_CONNECT - see TWiFi_SockConnect
    WIFI_EVENT_SOCKET_RECV - see TWiFi_Recv
    WIFI_EVENT_SOCKET_RECVFROM - see TWiFi_Recvfrom
    WIFI_EVENT_SOCKET_SEND - see TWiFi_Send
    WIFI_EVENT_SOCKET_SENDTO - see TWiFi_Send
    WIFI_EVENT_DNS_RESOLVE - see TWiFi_DNSResolve
    However, the data must be unpacked into the suitable structure using the rM2M_Pack() or rM2M_GetPackedB() function:
    new sScan[TWiFi_Scan]; /* unpack TWiFi_Scan structure */ rM2M_Pack (data, 0, sScan.sec, RM2M_PACK_GET|RM2M_PACK_U8); rM2M_Pack (data, 1, sScan.ch, RM2M_PACK_GET|RM2M_PACK_U8); rM2M_GetPackedB(data, 2, sScan.bssid, 6); rM2M_GetPackedB(data, 8, sScan.ssid, 32+1); rM2M_Pack (data, 41, sScan.rssi, RM2M_PACK_GET|RM2M_PACK_S8);
    len : s32 - Size of the data block in byte
    WiFi_Close()

    Closes the WiFi interface

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_GetState()

    Returns the current status of the WiFi interface

    returns : TWIFI_STATE - WiFi states
    WiFi_Scan()

    Starts the search for available WiFi networks on all channels supported by the installed WiFi module.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_Connect()

    Establishes a connection to an access point.

    The SSID of the network being used and the required configuration must be written in the "REG_APP_FLASH" registration memory block before calling up this function. The rM2M_RegSetString() function can be used for this purpose.
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_Disconnect()

    Disconnects the current connection to the access point.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    WiFi_GetRSSI()

    Starts determining the WiFi RSSI level [dBm].

    The device must be connected to an access point during this process. If the measurement is completed, the "WIFI_EVENT_RSSI" event is triggered by the system and the determined WiFi RSSI level [dBm] can be evaluated with the help of the callback function that is to be provided by the device logic developer (see TWiFi_Callback).
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_APCfg:

    Configuration for an access point

    sec : TWIFI_SEC - Encryption method
    ssid{32+1} : u8 - Service set identifier of the WiFi network that should be made available
    ssidHide : s32 - Specifies whether the network SSID should be hidden
    0 - SSID is visible
    1 - SSID should be hidden
    pwd{64+1} : astr - Authentication password (dependent on the encryption method)
    WIFI_SEC_WPA_PSK requires at least 9 characters!
    rfchnl : s32 - WiFi RF channel that should be used
    ip{4} : u8 - IP address of the access point (IPv4)
    WiFi_APInit(cfg[TWiFi_APCfg], len=sizeof cfg)

    Configures and activates the device in access point mode

    cfg : TWiFi_APCfg - Structure that contains the configuration for the access point
    len : s32 - Size (in cells) of the structure that contains the configuration for the access point
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWIFI_AF: u16

    Address families for socket connections

    WIFI_AF_INET = 2 - Address family used for IPv4
    TWIFI_SOCK_TYPE:

    Type of socket

    WIFI_SOCK_STREAM = 1 - reliable connection-oriented stream connection, i.e. TCP
    WIFI_SOCK_DGRAM = 2 - unreliable connectionless datagram connection, i.e. UDP
    Tsockaddr_in:

    Socket address information for IPv4 addresses. Either contains

  • Address family, port and IP address which should be assigned to a socket using the BIND operation,
  • Address family, port and IP address that should be used to establish a connection to a server using the CONNECT operation or
  • Address family, port and IP address of the server to which the data should be sent using via the SENDTO operation.
    • sin_family : TWIFI_AF - The address family that should be used
    sin_port : s32 - Port that should be used
    sin_addr[4] : s32
  • Server: IP address from which requests are accepted. Can be set to "0.0.0.0" to accept all IP addresses.
  • Client TCP: IP address of the server with which a connection should be established.
  • Client UDP: IP address of the server to which the data should be sent.
    • TWIFI_SOCK_ERR:

    Error codes for socket operations

    Error codes -15, -18, -20 intentionally omitted!
    WIFI_SOCK_ERR_INVALID_ADDRESS = -11
    Socket address is invalid.
    The socket operation cannot be completed successfully without specifying a specific address. For example: bind is called without specifying a port number
    WIFI_SOCK_ERR_ADDR_IN_USE = -12
    Socket operation cannot bind on the given address.
    With socket operations, only one IP address per socket is permitted. Any attempt for a new socket to bind with an IP address already bound to another open socket, will return this error code. States indicating that bind operation failed.
    WIFI_SOCK_ERR_MAX_TCP_SOCK = -13 - Exceeded the maximum number of TCP sockets
    WIFI_SOCK_ERR_MAX_UDP_SOCK = -14 - Exceeded the maximum number of UDP sockets
    WIFI_SOCK_ERR_INVALID_ARG = -16 - An invalid argument is passed to a function.
    WIFI_SOCK_ERR_MAX_LISTEN_SOCK = -17 - Exceeded the maximum number of TCP passive listening sockets
    WIFI_SOCK_ERR_INVALID = -19 - The requested socket operation is not valid in the current socket state.
    WIFI_SOCK_ERR_ADDR_IS_REQUIRED = -21 - Destination address is required.
    WIFI_SOCK_ERR_CONN_ABORTED = -22 - The socket is closed by the peer. The local socket is also closed.
    WIFI_SOCK_ERR_TIMEOUT = -23 - The socket pending operation has timed out
    WIFI_SOCK_ERR_BUFFER_FULL = -24 - No buffer space available to be used for the requested socket operation.
    WIFI_SOCK_ERR_RECV_BUF_FULL = -100 - Not enough space within recv buffer
    WIFI_SOCK_ERR_NO_MEMCTX = -101 - Memory context not available -> operation not possible
    WiFi_socket(domain, type, flags=0)

    Generates a socket. If a socket could be generated, it can be used immediately (synchronous operation).

    domain : TWIFI_AF - Address family used for the socket connection
    type : TWIFI_SOCK_TYPE - Type of generated socket ("WIFI_SOCK_STREAM" for TCP, "WIFI_SOCK_DGRAM" for UDP)
    flags : s32 - Reserved for extensions
    returns : Terror
    > = 0 - Socket, if a socket could be generated
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Bind:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_BIND" event.

    result : s8 - Result code of the BIND operation.
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_bind(socket, sockaddr[Tsockaddr_in])

    Assigns the address information (address family, port and IP address) to a socket (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_BIND" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket to which the address information should be assigned. The socket must be generated using the WiFi_socket() function beforehand.
    sockaddr : [Tsockaddr_in] - Structure that contains the address information
    returns : Terror
    OK - if the BIND operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Listen:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_LISTEN" event.

    result : s8 - Resultcode for LISTEN operation
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    TWiFi_Accept:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_ACCEPT" event. It contains information regarding a socket connection accepted by the system (WiFi module and firmware).

    socket : s8
    > = 0 - Socket via which the connection to the receiver is established
    < OK - socket error of type TWIFI_SOCK_ERR
    family : TWIFI_AF - Address family used for the socket connection
    port : u16 - Port via which the connection to the receiver is established
    addr{4} : u8 - IP address of the receiver
    WiFi_listen(socket)

    Prepares the socket to react to incoming connections (only necessary for connection-oriented stream connection, e.g. TCP server) (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_LISTEN" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer. If the LISTEN operation could be completed successfully, then the socket is ready for incoming connections. In the event of an incoming connection, the "WIFI_EVENT_SOCKET_ACCEPT" event is triggered, which must be evaluated by the callback function that is to be provided by the device logic developer.

    Before calling up this function, the address information must be assigned to the socket using the WiFi_bind() function.
    socket : s32 - Socket that should be prepared to react to incoming connections
    returns : Terror
    OK - if the LISTEN operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_SockConnect:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_CONNECT" event.

    result : s8 - Result code of the CONNECT operation
    0 - Operation completed successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_sockConnect(socket, remoteaddr[Tsockaddr_in])

    Establishes a TCP connection to a server (asynchronous operation). Once the operation is completed, the "WIFI_EVENT_SOCKET_CONNECT" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket that should be used for the TCP connection to the server. The socket must be generated using the WiFi_socket() function beforehand.
    remoteaddr : Tsockaddr_in - Structure that contains the address information (address family, port and IP address)
    returns : Terror
    OK - OK if the CONNECT operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Recv:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_RECV" event. It either contains the number of received bytes or specifies the error that has occurred.

    In the case of an error, the socket must be closed using the WiFi_sockClose() function.
    received : s16
    >0 - Number of received bytes
    0 - Socket closed
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_recv(socket, buf{}, len, timeout=0)

    Function to receive data via a TCP socket (asynchronous operation). Once data is received, the "WIFI_EVENT_SOCKET_RECV" event is triggered and the received data must be processed by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be received
    buf{} : u8 - Buffer to store received data (must be public)
    len : s32 - Size (in bytes) of the buffer to store the data to be received
    timeout : s32 - Timeout for receiving data in [ms]. 0...no timeout
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_Recvfrom:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_RECVFROM" event. It contains information regarding data received when using a connectionless network protocol (e.g. UDP).

    In the case of an error, the socket must be closed using the WiFi_sockClose() function.
    received : s16
    >0 - Number of received bytes
    0 - Socket closed
    < OK - socket error of type TWIFI_SOCK_ERR
    Socket must be closed using WiFi_sockClose() if error occured!
    family : TWIFI_AF - Address family used
    port : u16 - Port via which the data was received
    addr{4} : u8 - IP address of the sender of the data
    WiFi_recvfrom(socket, buf{}, len, timeout=0)

    Function to receive data via a UDP socket (asynchronous operation). Once data is received, the "WIFI_EVENT_SOCKET_RECVFROM" event is triggered and the received data must be processed by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be received
    buf{} : u8 - Buffer to store received data (must be public)
    len : s32 - Size (in bytes) of the buffer to store the data to be received
    timeout : s32 - Timeout for receiving data in [ms]. 0...no timeout
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sockMemCtx(socket, rxbuf{}, rxbuflen)

    Provides the firmware with a buffer from the RAM area reserved for the device logic for the specified socket. The transferred memory is used to internally process data in connection with the specified socket. The buffer should be assigned using this function immediately after generating the socket. As long as the socket has not been closed using the WiFi_sockClose() function, the transferred buffer may not be accessed via the device logic.

    socket : s32 - Socket for which the buffer should be made available
    rxbuf{} : u8 - Byte array that should be used as the receive buffer
    rxbuflen : s32 - Size of the receive buffer in byte
    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    TWiFi_Send:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_SOCKET_SEND" (TCP) and "WIFI_EVENT_SOCKET_SENDTO (UDP)" events.

    sent : s16
    >0 - Number of sent bytes
    < OK - socket error of type TWIFI_SOCK_ERR
    WiFi_send(socket, buf{}, len)

    Function to send data via a TCP socket (asynchronous operation). Once the data has been sent, the "WIFI_EVENT_SOCKET_SEND" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket : s32 - Socket via which the data should be sent
    buf{} : u8 - Buffer that contains the data to be sent
    The buffer must be "public". The content is changed by the send function as part of being processed.
    len : s32 - Number of bytes to be sent (max. 1400)
    returns : Terror
    >0 - Number of bytes accepted for processing if the SEND operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sendto(socket, buf{}, len, remoteaddr[Tsockaddr_in])

    Function to send data via a UDP socket (asynchronous operation). Once the data has been sent, the "WIFI_EVENT_SOCKET_SENDTO" event is triggered, which must be evaluated by the callback function (see TWiFi_Callback) that is to be provided by the device logic developer.

    socket - Socket via which the data should be sent
    buf{} : u8 - Buffer that contains the data to be sent
    The buffer must be "public". The content is changed by the send function as part of being processed.
    len : s32 - Number of bytes to be sent (max. 1400)
    remoteaddr : Tsockaddr_in - Structure that contains the address information (address family, port and IP address)
    returns : Terror
    >0 - Number of bytes accepted for processing if the SENDTO operation could be started successfully
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    WiFi_sockClose(socket)

    Closes the socket and releases all of the resources assigned to the socket (synchronous operation)

    All of the outstanding messages (to be sent or received) are discarded.
    socket : s32 - Socket that should be closed
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs
    TWiFi_DNSResolve:

    Structure of the data to be evaluated via callback in case of the "WIFI_EVENT_DNS_RESOLVE" event.

    ip{4} : u8 - Resolved IPv4 address or 0.0.0.0 in the event of an error
    WiFi_gethostbyname(const hostname{})

    Asynchronous function to resolve a host name (e.g. URL) into a host IP address using the domain name system (DNS). The IP address of a DNS server must be saved to be able to execute the operation correctly. This address must either be obtained from the access point when using DHCP or must be written in the "REG_APP_FLASH" registration memory block. The rM2M_RegSetString() function can be used for this purpose. If the resolution of the host name is completed (OK or NOT OK), the "WIFI_EVENT_DNS_RESOLVE" event is triggered by the system and the determined IP address can continue to be processed with the help of the callback function that is to be provided by the device logic developer (see TWiFi_Callback).

    hostname{} : astr - Host name (e.g. URL) for which the associated IP address should be determined
    returns : Terror
    OK - if successful
    < OK - socket error of type TWIFI_SOCK_ERR
    ERROR - if an unspecified error occurs

    FILE

    M23X:

    TFileHandle

    Handle for a specific file

    TFileError: s32

    Return codes for file operations

    FILE_DISK_ERR = -1 - A hard error occurred in the low level disk I/O layer
    FILE_INT_ERR = -2 - Assertion failed
    FILE_NOT_READY = -3 - The physical drive cannot work
    FILE_NO_FILE = -4 - Could not find the file
    FILE_NO_PATH = -5 - Could not find the path
    FILE_INVALID_NAME = -6 - The path name format is invalid
    FILE_DENIED = -7 - Access denied due to prohibited access or directory full
    FILE_EXIST = -8 - Access denied due to prohibited access
    FILE_INVALID_OBJECT = -9 - The file/directory object is invalid
    FILE_WRITE_PROTECTED = -10 - The physical drive is write protected
    FILE_INVALID_DRIVE = -11 - The logical drive number is invalid
    FILE_NOT_ENABLED = -12 - The volume has no work area
    FILE_NO_FILESYSTEM = -13 - There is no valid FAT volume
    FILE_MKFS_ABORTED = -14 - The f_mkfs() aborted due to any problem
    FILE_TIMEOUT = -15 - Could not get a grant to access the volume within defined period
    FILE_LOCKED = -16 - The operation is rejected according to the file sharing policy
    FILE_NOT_ENOUGH_CORE = -17 - LFN working buffer could not be allocated
    FILE_TOO_MANY_OPEN_FILES = -18 - Number of open files > _FS_LOCK
    FILE_INVALID_PARAMETER = -19 - Given parameter is invalid
    TFileMode: s32

    File access modes for the function fopen()

    FILE_IO_READ = 0 - Opens the file to be read; the file must be available
    FILE_IO_WRITE = 1 - Creates a new file
    FILE_IO_READWRITE = 2 - Opens an existing file or creates a new file
    FILE_IO_APPEND = 3 - Attach to an existing file (write-only)
    TFileRefPos:

    Reference position within the file for the function fseek()

    FILE_SEEK_START = 0 - Start of the file
    FILE_SEEK_CURRENT = 1 - Current read/write position
    FILE_SEEK_END = 2 - End of the file
    TFileAttributes:

    File attributes (bitmask)

    FILE_AM_RDO = 0x01 - Write-protected
    FILE_AM_HID = 0x02 - Hidden
    FILE_AM_SYS = 0x04 - System file
    FILE_AM_DIR = 0x10 - Directory
    FILE_AM_ARC = 0x20 - Archive
    EOF - -1

    End of file indication

    fsetbuf(buf{}, size)

    Provides the firmware with a memory to manage the files from the RAM area reserved for the device logic.

    This function must be called up before opening a file via the fopen() function.
    The buffer "buf" must be valid during the entire use by the firmware (i.e. it must be defined as a global or static variable).
    buf{} : u8 - Static byte array that should be used as the memory
    size : s32 - Size of the memory in bytes
    returns : TFileError
    >=0 - Number of files (i.e. file handle) that can be open at the same time.
    FILE_INT_ERR - If the fsetbuf() function has already been called up once before (fsetbuf() must only be called up once for the entire runtime of the device logic)
    FILE_INVALID_PARAMETER - If the transferred memory is too small to be able to manage at least one file.
    <OK - If another error occurs, see TFileError
    fopen(&File: handle, const name{}, mode = FILE_IO_READWRITE)

    Opens a file and supplies the file handle that is required for the following file operations.

    handle : TFileHandle - Variable (with the tag "File:") to store the file handle.
    name : astr - Name of the file to be opened (complete file path, if the file is not in the root directory).
    The complete file path must not be longer than 200 characters and must not contain umlauts or special characters. "\" must be used to separate directories.
    mode : TFileMode - Mode in which the file should be opened.
    For this parameter, only use the predefined constants for the file access mode, see TFileMode.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    fclose(File: handle)

    Closes an open file.

    handle : TFileHandle - Handle for a specific file (initialised by the fopen() function).
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    fremove(const name{})

    Deletes an existing file or subdirectory.

    Directory is only deleted if it is empty (i.e. it must not contain any files or subdirectories).
    name : astr - Name of the file or directory that should be deleted (complete file path, if the file or directory is not in the root directory).
    The complete file path must not be longer than 200 characters and must not contain umlauts or special characters. "\" must be used to separate directories.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    frename(const oldname{}, const newname{})

    Renames an existing file or subdirectory.

    oldname : astr - Current name of the file or directory (complete file path, if the file or directory is not in the root directory).
    The complete file path must not be longer than 200 characters and must not contain umlauts or special characters. "\" must be used to separate directories.
    newname : astr - New name of the file or directory (complete file path, if the file or directory is not in the root directory).
    The new name can also include a different file path to the one for the current name, as long as the directories being used already exist.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    fmkdir(const name{})

    Creates a new directory.

    name : astr - Name of the new directory to be created (complete file path if the directory should not be created in the root directory).
    The complete file path must not be longer than 200 characters and must not contain umlauts or special characters. "\" must be used to separate directories.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    flistdir(funcidx, const path{}={0})

    Lists all of the files and subdirectories in the specified directory.

    funcidx : s32 - Index of the public function that is called up once for every file and every subdirectory found in the specified directory.

    Type of the function (see Tflistdir_Callback):
    public func(name{}, size, fattime, mode);
    path : astr - Complete file path of the directory for which the content (files and subdirectories) should be listed.
    The complete file path must not be longer than 200 characters and must not contain umlauts or special characters. "\" must be used to separate directories.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    Tflistdir_Callback(
    public func(name{}, size, fattime, mode);
    Function to be made available by the device logic developer, that is called up once for every file and every subdirectory that is found when a request to list the content (files and subdirectories) of a directory has been made via the flistdir() function (registered with flistdir() ).
    name{} : u8
  • Name of found file or subdirectory
  • Empty string to indicate that there are no more files or subdirectories in the current directory
    • size : s32 - File size in bytes
    fattime : s32 - Time stamp for last change to the file (FAT timestamp format).
    mode : TFileAttributes - Attributes of the found file
    fwrite(File: handle, const buffer{}, len)

    Writes data in to a file.

    handle : TFileHandle - Handle for a specific file (initialised by the fopen() function).
    buffer{} : u8 - Array that contains the data to be written in the file.
    len : s32 - Number of bytes to be written.
    returns : TFileError
    >=0 - Number of written bytes, if successful (corresponds to the number specified for the "len" parameter).
    <OK - If an error occurs, see TFileError
    fread(File: handle, buffer{}, len)

    Reads data out of a file.

    handle : TFileHandle - Handle for a specific file (initialised by the fopen() function).
    buffer{} : u8 - Array to store the data read out of the file.
    len : s32 - Number of bytes to be read.
    returns : TFileError
    >=0 - Number of read bytes, if successful (corresponds to the number specified for the "len" parameter).
    <OK - If an error occurs, see TFileError
    fseek(File: handle, position = 0, whence = FILE_SEEK_START)

    Specifies the position within a file from which the data should be written/read.

    handle : TFileHandle - Handle for a specific file (initialised by the fopen() function).
    position : s32 - Offset (based on the reference position specified via the "whence" parameter) to specify the position within a file from which the data should be written/read.
    Positive and negative values are permissible as long as the file limits are not exceeded.
    whence : TFileRefPos - Reference position within the file (start of the file, current read/write position or end of the file).
    For this parameter, only use the predefined constants for the reference position within the file, see TFileRefPos.
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    flength(File: handle)

    Returns the size of a file.

    handle : TFileHandle - Handle for a specific file (initialised by the fopen() function).
    returns
    >=0 - File size
    FILE_INVALID_OBJECT - If an error occurs
    fstat(const name{}, &size = 0, &fattime = 0, &mode = 0)

    Returns information regarding a file or subdirectory.

    name : astr - Name of the file or directory for which the information is required (complete file path, if the file or directory is not in the root directory).
    size : s32 - Variable to store the size in bytes
    fattime : s32 - Variable to store the time stamp of the last change (FAT timestamp format)
    attr : TFileAttributes - Variable to store the attributes, see TFileAttributes
    returns : TFileError
    OK - If successful
    <OK - If an error occurs, see TFileError
    fgetfree()

    Specifies the size of the free memory in the file system.

    returns
    >=0 - Number of free bytes in the file system.
    <OK - If an error occurs, see TFileError.

    NVRAM

    M23X:

    TNVRAM_Info:

    Information regarding NVRAM

    size : s32 - Number of available bytes
    NVRAM_GetInfo(info[TNVRAM_Info], len=sizeof info)

    Returns information about the NVRAM.

    info : TNVRAM_Info - Structure for storing information about the NVRAM
    len : s32 - Size (in cells) of the structure to store the information - OPTIONAL
    returns : Terror
    >=0 - Size (in cells) of the structure used to store the information
    ERROR_NOT_SUPPORTED - If no NVRAM is available on this hardware
    ERROR - If another error occurs
    NVRAM_Read(addr, const data{}, len)

    Reads data out of the NVRAM.

    addr : s32 - Start address within the NVRAM from which the data should be read.
    data{} : u8 - Array to store the data read out of the NVRAM.
    len : s32 - Number of bytes to be read.
    returns : Terror
    OK - If succssful
    ERROR_NOT_SUPPORTED - If no NVRAM is available on this hardware
    ERROR - If another error occurs
    NVRAM_Write(addr, const data{}, len)

    Writes data in to the NVRAM.

    addr : s32 - Start address within the NVRAM from where the data should be written.
    data{} : u8 - Array that contains the data to be written in the NVRAM.
    len : s32 - Number of bytes to be written
    returns : Terror
    OK - If succssful
    ERROR_NOT_SUPPORTED - If no NVRAM is available on this hardware
    ERROR - If another error occurs

    USB HOST

    M23X:

    TusbhEvents:

    USB Host events

    USBH_EVENT_NONE = 0
    USBH_EVENT_SELECT_CONFIGURATION = 1 - USB device configuration has to be selected
    USBH_EVENT_CLASS_ACTIVE = 2 - USB device class active
    USBH_EVENT_CLASS_SELECTED = 3 - USB device class selected
    USBH_EVENT_CONNECTION = 4 - New device connection detected
    USBH_EVENT_DISCONNECTION = 5 - Device disconnection detected
    USBH_EVENT_UNRECOVERED_ERROR = 6 - Unrecoverable error
    USBH_EVENT_CLASS_ABORTED = 7 - USB device class unknown
    Class specific events
    USBH_EVENT_CDC_RX = 100 - CDC class data received
    USBH_EVENT_CDC_TXDONE = 101 - CDC class data transmitted
    TUSBH_DevDesc:

    Descriptor structure for USB devices

    VID : s32 - Vendor ID
    PID : s32 - Product ID
    Class : s32 - Interface Class
    SubClass : s32 - Interface SubClass
    Protocol : s32 - Interface Protocol
    Mfc{32} : astr - Device Manufacturer String
    Prd{32} : astr - Device Product String
    SN{32} : astr - Device SerialNumber String
    USBH_Init(funcidx)

    Initialises and configures the USB host interface.

    funcidx : s32 - Index of the public function that is called up if a USB host event has occurred.

    Type of the function (see TUSBH_Callback):
    public func( addr, event, const data{}, len);
    Terror
    OK - If successful
    ERROR - If an error occurs
    TUSBH_Callback(
    public func(addr, event, const data{}, len);
    Function to be provided by the device logic developer, that is called up if a USB host event has occurred (registered with USBH_Init() ).
    addr : s32 - USB device address
    event : TusbhEvents - USB host event that has occurred
    data{} : u8 - Array for which the content is dependent on the type of USB host event:
  • USBH_EVENT_CLASS_ACTIVE: Descriptor structure of the USB device, see TUSBH_DevDesc
  • USBH_EVENT_CLASS_ABORTED: Descriptor structure of the USB device, see TUSBH_DevDesc
  • USBH_EVENT_CDC_RX: CDC data received from the USB device
    • len : s32 - Number of bytes in the array
    USBH_Close()

    Closes and deactivates the USB host interface.

    Terror
    OK - If successful
    ERROR - If an error occurs
    USBH_CDCTx(addr, const data{}, len)

    Sends CDC data to a USB device.

    The command works in non-blocking mode. The "USBH_EVENT_CDC_TXDONE" event is triggered when the data has been sent to the USB device (see TusbhEvents).
    addr : s32 - USB device address
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent (max. 1024)
    returns : Terror
    >=0 - Number of processed bytes, if successful
    ERROR - If one of the following errors occurs:
  • USB host interface was not initialised via the USBH_Init() function
  • Invalid USB device address
  • Memory area (data{}, len) is invalid

    • BLE & LTE-M Gateway

    Description

    Standard library for the rapidM2M Studio ecosphere

    HARDWARE

    M2BLEGW:

    boardref:
     

    CLASSIC STYLE

    BLEGW_SensorDetect_Init()→ BLEDisplay_SetValues()Display_On()→ DISPLAYBLEGW_GetSysValues()Switch_Init()→ BUTTONPM_GetInfo()PM_BackupInit()→ POWER SUPPLY

    BLE

    M2BLEGW:

    BLEGW_SensorDetect_Init(funcidx)

    init and configure sensor detection interface

    cb : TBLEGW_OnSensorDetect
    returns : Terror - OK, ERROR
    TBLEGW_OnSensorDetect(key)

    called on sensor detection state change

    public func(key);
    param <key> cant be true!
    BLEGW_SensorDetect_Close()

    close and deactivate sensor detection interface

    returns : Terror - OK, ERROR
    TBLEGW_Id:

    identification structure of BLE chip

    FWVersion - firmware version of BLE chip
    BLEGW_GetId(out id[TBLEGW_Id], _cellCnt=sizeof id)

    retrieve identification of BLE chip

    id : TBLEGW_Id - result buffer
    _cellCnt : s32
    returns : Terror
    > = 0 - number of cells filled with data in id buffer
    ERROR - address/length pair for id buffer is invalid
    BLE_MAX_CONNECTIONS - 5

    Maximum BLE connections

    Maximum number of simultaneous BLE connections
    BLE_SetScanResponseData(const data{}, size)

    Sets manufacturer specific data which is part of the response when a BLE central performes an active scan.

    data{} : u8 - Array that contains the data for the scan response
    size : s32 - Size of data (in cells)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    BLE_ActivateSensorsupply(turnOn, funcidx)

    activate or deactivate sensor supply

    Sensor supply is also on while modem is enabled!
    turnOn : s32 - 0=off, any other value = on
    cb : TBLEGW_OnSensorSupplyChange
    returns : Terror
    TBLEGW_OnSensorSupplyChange(onOff)

    called on sensor supply on or off

    public func(onOff);
    Function is called if sensor supply is turned on(true) or off(false) from device.
    BLE_Init(funcidx)

    initialises the BLE interface and specifies the function that should be called up if a BLE event has occurred

    The "BLE_EVENT_DEVINFO" event is triggered as soon as the BLE module is ready.
    funcidx : s32 - Index of the public function that is called up if a BLE event has occurred.

    Type of the function (see TBLE_Callback):
    public func(event, connhandle, const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the BLE module is not unlocked on the device
    ERROR - if any other error occurs
    TBLE_event(event, connhandle, const data{}, len)

    callback registered with BLE_Init

    public func(event, connhandle, const data{}, len);
    event : s32
    BLE_EVENT_SCAN = 0
    BLE_EVENT_SCAN_RSP = 1
    BLE_EVENT_NOTIFY = 2
    BLE_EVENT_READ = 3
    connhandle : s32
    data{} : TBLE_Scan|TBLE_Notify|TBLE_Read - structure depends on
    len : s32 - number of valid bytes in
    TBLE_Scan:

    Information regarding a BLE peripheral found during a (passive or active) scan process (used with TBLE_event() callback)

    addr_type : s32 - Type of BLE address
    0 - Public address
    1 - Random static address
    2 - Random private resolvable address
    3 - Random private non-resolvable address
    addr{6} : u8 - HW address
    rssi : s32 - Signal strength [dBm]
    name{32+1} : astr - Advertising name of the peripheral
    msd_len : s32 - Number of bytes saved in "msd"
    msd{32} : u8 - Manufacturer-specific data
    TBLE_Notify:

    Content/data of a characteristic for which the notification was activated

    charHandle : s32 - Handle of a characteristic
    len : s32 - Number of received bytes
    data{BLE_MAXLEN_NOTIFY} : u8 - Array that contains the received data
    TBLE_Read:

    Block of requested data from a characteristic

    charHandle : s32 - Handle of a characteristic
    offset : s32 - Offset of the received data block within the characteristic
    len : s32 - Number of available bytes in the data array
    data{BLE_MAXLEN_READ} : u8 - Array that contains the received data
    BLE_Close()

    Deactivates the BLE interface. In doing so, the connection to the sensors connected at this time is also automatically disconnected.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    BLE_Reset()

    reset BLE interface

    returns : Terror
    BLE_GetState()

    Returns the current status of the BLE interface

    returns : BLE_STATE_x - Status of the BLE interface
    BLE_Scan(time = 10, flags = 0)

    Starts the scan process according to the BLE peripherals

    The command works in non-blocking mode. The "BLE_EVENT_SCAN" event (passive scan) or "BLE_EVENT_SCAN_RSP" event (active scan) is triggered every time a BLE peripheral has been found. The "BLE_EVENT_SCAN_FINISHED" event is triggered when the scan process is completed (i.e. the scan duration has expired). Once the scan process is completed, the BLE_GetState() function returns "BLE_STATE_READY" instead of "BLE_STATE_BUSY".
    time : s32 - Scan duration [s]
    flags : s32 - Type of BLE scan
    0 - passive scan (most energy-efficient)
    1 - active scan (scan request)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if another error occurs
    BLE_Connect(addr{6}, itv = -1)

    Establishes the connection to a BLE peripheral

    The command works in non-blocking mode. The "BLE_EVENT_CONNECT" event is triggered if
  • the connection to a BLE peripheral could be established,
  • an existing connection was interrupted or
  • an error occurred when establishing a connection.
    • addr{} : u8 - HW address of the BLE peripheral with which the connection should be established.
    itv : s32 - BLE connection interval in [ms] (i.e. interval at which the data is exchanged) (Valid values: 8...1000 ms)
    returns : s32
    >= 0 - Connection handle of a certain BLE peripheral if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_Disconnect(connhandle = 0)

    Disconnects the connection to a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_CONNECT" event is triggered if
  • the connection to a BLE peripheral could be disconnected,
  • an error occurred when disconnecting the connection.
    • connhandle : s32 - Connection handle of a certain BLE peripheral
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_GetConnState(connhandle = 0)

    Returns the connection status for a certain BLE peripheral

    connhandle : s32 - Connection handle of a certain BLE peripheral
    returns : s32
    >0 - Connected
    0 - Connection disconnected
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR = if one of the following errors occurs
  • invalid handle
  • any other error
    • BLE_Write(connhandle = 0, handle, const data{}, size)

    Writes data in a certain characteristic of a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_WRITE_RESULT" event is triggered if the data was successfully written in the characteristic of the BLE peripheral or an error occurred while the data was being written.
    connhandle : s32 - Connection handle of a certain BLE peripheral
    handle : s32 - Handle of a certain characteristic (currently has to be determined externally)
    data{} : u8 - Array that contains the data to be written in the characteristic
    size : s32 - Number of bytes to be written
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_Read(connhandle = 0, handle)

    Reads data from a certain characteristic of a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_READ" event is triggered every time a block of the requested data has been received. The "BLE_EVENT_READ_RESULT" event is triggered if all of the requested data was received or an error occurred while reading the data.
    connhandle : s32 - Connection handle of a certain BLE peripheral
    handle : s32 - Handle of a certain characteristic (currently has to be determined externally)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_ChgConItv(connhandle = 0, conitv)

    Changes the BLE connection interval (i.e. interval at which the data is exchanged)

    The BLE peripheral must already be connected
    connhandle : s32 - Connection handle of a certain BLE peripheral
    conitv : s32 - BLE connection interval in [ms] (i.e. interval at which the data is exchanged) (Valid values: 8...1000 ms)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_GetId(id[TBLE_Id], len=sizeof id)

    Returns the information to identify the BLE module installed in the device

    id : TBLE_Id - Structure for storing the information to identify the BLE module installed in the device
    len : s32 - Size (in cells) of the structure to store the information
    returns : s32
    > = 0 - Size (in cells) of the structure used to store the information
    ERROR - if one of the following errors occurs
  • if the address and/or length of the ID structure are invalid (outside the device logic data memory)
  • the BLE module is not ready
    • TBLE_Callback(
    public func(event, connhandle, const data{}, len);
    Function to be provided by the device logic developer,
    that is called up if a BLE event has occurred (registered with BLE_Init() ).
    event : BLE_EVENT_x - BLE event that has occurred
    connhandle : s32 - Connection handle of a certain BLE peripheral
    data{} : u8 - Array for which the content is dependent on the type of BLE event:
    BLE_EVENT_SCAN - Information on a BLE peripheral found during a scan process (see TBLE_Scan). This event is triggered if a BLE peripheral was found during scanning (passive) (see BLE_Scan()).
    BLE_EVENT_SCAN_RSP - Information on a BLE peripheral found during a scan process (see TBLE_Scan). This event is triggered if a BLE peripheral was found during scanning (active) (see BLE_Scan()).
    BLE_EVENT_NOTIFY - Content/data of a characteristic for which the notification was activated (see TBLE_Notify). This event is triggered if the software of the BLE peripheral changes the content of a characteristic for which the notification was previously activated.
    BLE_EVENT_READ - Block of required data from a characteristic (see TBLE_Read). This event is triggered if a block of the requested data was received (see BLE_Read()).
    BLE_EVENT_WRITE_RESULT - Information on how the write process on a characteristic was completed (see TBLE_WriteResult). This event is triggered if the data was successfully written in the characteristics of the BLE peripheral or an error occurred during this process (see BLE_Write()).
    BLE_EVENT_READ_RESULT - Information on how the read process on a characteristic was completed (see TBLE_ReadResult). This event is triggered if all of the requested data was received or an error occurred during this process (see BLE_Read()).
    BLE_EVENT_SCAN_FINISHED - Information on how a scan process was completed (see TBLE_ScanFinished). This event is triggered when the scan process is completed (see BLE_Scan()).
    BLE_EVENT_DEVINFO - Information to identify the BLE module installed in the device (see TBLE_DevInfo). This event is triggered if the BLE module has been initialised via BLE_Init() and is ready.
    BLE_EVENT_CONNECT - Information regarding the status change of the connection with a BLE peripheral (see TBLE_Connect). This event is triggered if the connection to a BLE peripheral could be established/disconnected or if an error was triggered (see BLE_Connect() and BLE_Disconnect()).
    BLE_EVENT_ERROR - Information regarding which error has occurred (see TBLE_Error). This event is triggered if an internal error occurs.
    BLE_EVENT_RAWCMD_STRING - String that was sent by the BLE module as a response to the RAW command. This event is triggered if a STRING/ASCII response is available for a RAW command sent via BLE_SendRawCmd() to the BLE module.
    BLE_EVENT_RAWCMD_OK - "OK". This event is triggered if a RAW command sent via BLE_SendRawCmd() to the BLE module has been terminated successfully.
    BLE_EVENT_RAWCMD_ERROR - "ERROR". This event is triggered if a RAW command sent via BLE_SendRawCmd() to the BLE module could not be processed or failed.
    len : s32 - Number of bytes in the array
    BLE_SendRawCmd(cmd{}, cmdlen, timeout=0)

    Sends RAW commands to the BLE module.

    A RAW command is forwarded directly to the BLE module by the firmware. The developer of the device logic is responsible for developing the RAW commands that are suitable for the BLE module (e.g. stop advertising on NRF5x scanner app: "at+advertise=0\r\n").
    The command works in non-blocking mode. Depending on whether the BLE module could process the RAW command, one of the following events is triggered:
  • BLE_EVENT_RAWCMD_STRING: STRING/ASCII response available
  • BLE_EVENT_RAWCMD_OK: Command completed successfully
  • BLE_EVENT_RAWCMD_ERROR: Command failed
    • cmd{} : u8 - Array that contains the RAW commands to be sent
    cmdlen : s32 - Number of bytes that make up the RAW command
    If the BLE module expects ASCII commands (e.g. NRF5x scanner app), then the final '\0' after the RAW command must be added to the RAW command by the user.
    timeout : s32 - Response timeout
    0 - Internal default timeout is used
    >0 - Response timeout in [ms]
    returns : s32
    OK - if successful
    ERROR - if another error occurs
    BLE_Setbuf(rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the BLE interface from the RAM area reserved for the device logic. When this function is called up, the system switches from the 256 bytes buffers integrated in the firmware to the transferred buffers.

    If required, this function must be called via the BLE_Init() function before the BLE interface is initialised.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the BLE interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the BLE interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the BLE module is not released on the device
    ERROR - if an error occurs
    < OK - if another error occurs - see Terror
    TBLE_Id:

    Information to identify the BLE module installed in the device

    In contrast to the information that is contained in the TBLE_DevInfo structure, this information can be called up at any time via the BLE_GetId() function.
    FWVersion : s32 - Version of the application installed on the BLE module
    The minor version is saved in byte 0, the major version is saved in byte 1. e.g. "01v003": Major version = 1, Minor version = 3.
    TBLE_ScanFinished:

    Information on how a scan process (passive or active) was completed

    result : s32 - specifies how the scan process was terminated
    OK - Scan process completed successfully
    ERROR - An error occurred
    ERROR-1 - Timeout
    TBLE_WriteResult:

    Information on how the write process on a characteristic was completed

    result : s32 - specifies how the write process was terminated
    OK - Write process completed successfully
    ERROR - An error or timeout occurred
    charHandle : s32 - Handle of the characteristic
    len : s32 - Number of written bytes, if successful
    TBLE_ReadResult:

    Information on how the read process on a characteristic was completed

    result : s32 - specifies how the read process was terminated
    OK - Read process completed successfully
    ERROR - An error or timeout occurred
    charHandle : s32 - Handle of the characteristic
    TBLE_DevInfo:

    Information to identify the BLE module installed in the device.

    This information is provided once via the TBLE_event() callback function ("BLE_EVENT_DEVINFO" event) if the BLE module is initialised via BLE_Init().
    chipname{BLE_MAXLEN_CHIPNAME+1} : astr - Ascii, designation of the BLE module (e.g. NRF52)
    appname{BLE_MAXLEN_APPNAME+1} : astr - Ascii, designation of the application installed on the BLE module (e.g. ScannerApp)
    hwrev{BLE_MAXLEN_HWREV+1} : astr - Ascii, HW revision (e.g. "01v001") (reserved for extensions)
    fwrev{BLE_MAXLEN_FWREV+1} : astr - Ascii, FW version (z.B. "02v000") of the application installed on the BLE module
    addr{6} : u8 - HW address (all bytes are zero, if not available)
    TBLE_Connect:

    Information regarding the status change of the connection with a BLE peripheral

    result : s32 - Status of the connection
    1 - disconnected
    0 - connected
    <0 - ERROR
    addr{6} : u8 - HW address of the BLE peripheral
    TBLE_Error:

    Information regarding which error has occurred

    errorcode : Terror
    BLE_EVENT_x:

    Possible BLE events for the callback function TBLE_event()

    BLE_EVENT_SCAN = 0 - BLE Central: Scan information available (passive scan)
    BLE_EVENT_SCAN_RSP = 1 - BLE Central: Scan information available (active scan)
    BLE_EVENT_NOTIFY = 2 - BLE Central: Notification received
    BLE_EVENT_READ = 3 - BLE Central: Read response data available
    BLE_EVENT_WRITE_RESULT = 4 - BLE Central: Write command is terminated
    BLE_EVENT_READ_RESULT = 5 - BLE Central: Read command is terminated
    BLE_EVENT_SCAN_FINISHED = 6 - BLE Central: The scan process is terminated
    BLE_EVENT_DEVINFO = 7 - Device information available (BLE module is ready)
    BLE_EVENT_CONNECT = 8 - BLE Central: Connected to/disconnected from peripheral
    BLE_EVENT_ERROR = 9 - Internal error has occurred
    BLE_EVENT_RAWCMD_STRING = 10 - RAW command: STRING/ASCII response available
    BLE_EVENT_RAWCMD_OK = 11 - RAW command: OK response available (command terminated successfully)
    BLE_EVENT_RAWCMD_ERROR = 12 - RAW command: ERROR response available (command failed)
    BLE_STATE_x:

    Status of the BLE interface.

    Return values of the BLE_GetState() function.
    BLE_STATE_OFF = 0 - The BLE interface is switched off
    BLE_STATE_INIT = 1 - Init sequence active, not ready (yet)
    BLE_STATE_READY = 2 - Ready for the receipt of commands
    BLE_STATE_BUSY = 3 - A command is currently being processed
    BLE_MAXLEN_NOTIFY - 256

    Size of the notification data area

    Maximum size (in bytes) of the data area of a notification
    BLE_MAXLEN_READ - 256

    Size of the data area of a read data block

    Maximum size (in bytes) of the data area of a requested data block from a characteristic
    BLE_ERROR_x:

    BLE error codes

    BLE_ERROR_UNKNOWN = 0 - Unspecified internal error
    BLE_ERROR_INIT = 1 - Initialisation error
    BLE_ERROR_IO = 2 - Internal IO error
    BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
    BLE_ERROR_FORCED_DISC = 4 - Forced disconnect error
    BLE_MAXLEN_CHIPNAME - 20

    Max. length of the designation for the BLE module

    BLE_MAXLEN_APPNAME - 20

    Max. length of the designation for the application installed on the BLE module

    BLE_MAXLEN_HWREV - 20

    Max. length for the string that specifies the HW revision

    BLE_MAXLEN_FWREV - 20

    Max. length for the string that specifies the FW revision

    BLE_CHIPNAME_NRF52 - "NRF52"

    Designation of the BLE module installed in the device

    BLE_APPNAME_SCANNER_APP - "ScannerApp"

    Designation of the application installed on the BLE module

    SYSTEM

    M2BLEGW:

    TBLEGW_SysValue:

    retrieve sys values of device

    Temp : s32 - temperature [0.1°C]
    RH : s32 - relative humidity [0.1%rH]
    BLEGW_GetSysValues
    BLEGW_GetSysValues(out values[TBLEGW_SysValue], _cellCnt=sizeof values);
    values : TBLEGW_SysValue - result buffer
    _cellCnt : s32
    returns : Terror
    > = 0 - number of cells filled with data in values buffer
    ERROR - address/length pair for values buffer is invalid or a sys value is invalid

    SWITCH

    M2BLEGW:

    Switch_Init(mode, funcidx=-1)

    Initialises the solenoid switch

    mode : s32 - Selection of whether the solenoid switch is evaluated by the firmware or device logic
    SWITCH_MODE_INTERNAL = 0 - evaluation by the FW
    If the button was pressed and held for 3 sec., a transmission is initiated when the button is released.
    SWITCH_MODE_SCRIPT = 1 - evaluation by the device logic
    In the event of a state change of the button (press or release), the public function, for which the index was transferred to the Switch_Init() function, is called.
    funcidx : s32 - Index of the public function that should be executed in the event of a state change of the button (only necessary if mode=SWITCH_MODE_SCRIPT)

    Type of the function (see TSwitch_Callback):
    public func(key);
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TSwitch_Callback(
    public func( key);
    Function to be provided by the device logic developer, that is called when the state of the button changes (registered with Switch_Init() ).
    key : s32 - Indicates which state change called the function
    0 - Button was released
    1 - Button was pressed
    Switch_Close()

    Deactivates the solenoid switch. An action is no longer initiated when the button is pressed.

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    DISPLAY

    M2BLEGW:

    BLEGW_Display_Init(aDisplayBuffer{}, len=sizeof aDisplayBuffer)

    init display

    aDisplayBuffer
    len : s32
    returns : Terror - OK, ERROR
    BLEGW_Display_On()

    power on display (needs 300ms to execute)

    returns : Terror - OK, ERROR
    BLEGW_Display_Off()

    power off display

    returns : Terror - OK, ERROR
    BLEGW_Display_AddElement(sDisplayElement[TDisplayElement], len=sizeof sDisplayElement)

    add an element to the display

    sDisplayElement : TDisplayElement
    len : s32
    returns : s32
    >= 0 - ElementID if succesful
    ERRROR - if error occours
    BLEGW_Display_RemoveElement(iElementId)

    remove an element from the display

    iElementId
    returns : Terror - OK, ERROR
    BLEGW_Display_SetElement(iElementId, ...)

    set content of an element

    iElementId
    TDisplayElement : r TStringElement or TQRCodeElement, depends on elemnt type
    returns : Terror - OK, ERROR
    BLEGW_Display_ClearElement(iElementId)

    clear content of an element

    iElementId
    returns : Terror - OK, ERROR

    POWER MANAGEMENT

    M2BLEGW:

    PM_SetChargingMode(mode)

    Sets the charge mode.

    mode : TPM_CHARGING_MODE
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    PM_BackupInit(funcidx)

    Activates malfunction monitoring for the supply or charging voltage V IN and specifies the function that should be called up in the event of the supply or charging voltage V IN failing.

    funcidx - Index of the public function that should be called up if a failure of the supply or charging voltage V IN has been detected.

    Type of the function (see TPM_Callback):
    public func();
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    TPM_Callback(
    public func();
    Function to be provided by the device logic developer, that is called up if a failure of the supply or charging voltage V IN has been detected (registered with PM_BackupInit() ).
    PM_BackupClose()

    Deactivates malfunction monitoring for the supply or charging voltage V IN

    returns : Terror
    OK - if successful
    PM_GetInfo(info[TPM_Info], len=sizeof info)

    Provides information on the energy source used and power management status

    info : TPM_Info - Structure for storing the information
    len : s32 - Size (in cells) of the structure to store the information
    returns : Terror
    >= OK - used size (in cells) of the structure for storing the information
    ERROR - if an invalid parameter was transferred
    PM_GetCoulombCounter(flags=0)

    Reads the current state of the Coulomb counter (electric charge) that can be used for the application derived from the system's internal Coulomb counter

    flags : s32 - Configuration flags to be set/deleted
    Bit0 - Resetting the Coulomb counter that can be used for the application
  • 0 - no action
  • PM_CC_RESET = 0x00000001 - Counter reset
    • returns : s32 - Depleted electric charge [mAs] since the last reset of the Coulomb counter that can be used for the application
    TPM_CHARGING_MODE:
    PM_CHARGING_OFF = 0 - Charge control deactivated
    PM_CHARGING_NORMAL = 1 - Charge if the state of charge of the rechargeable battery is <50%.
    PM_CHARGING_SOLAR = 2 - Charge continuously, if possible, and the supply or charging voltage V IN is above 16V.
    TPM_Info:

    Information on the energy source used and power management status

    → PM_GetInfo()
    BatteryType : s32 - PSU type
    PM_BATT_TYPE_NONE = 0 - No battery or external power supply
    PM_BATT_TYPE_NORMAL = 1 - Battery, only discharged
    PM_BATT_TYPE_LIIO = 2 - Li-ion rechargeable battery
    Flags : s32 - Power management status
    PM_FLAG_CHARGING = 0x00000001 - Charge control active
    PM_FLAG_BACKUP = 0x00000002 - Supply via internal energy source following failure of V IN (only if V IN monitoring was activated)
    PM_FLAG_ERROR = 0x00000008 - Power management error (does not charge, SoC cannot be determined, because the memory of the power supply unit could not be read, for example)
    VIn : s32 - Supply or charging voltage V IN in [mV]
    VBatt : s32 - Battery or rechargeable battery voltage in [mV]
    SOC : s32 - State of charge in [0.01%]
    PIn : s32 - Power consumption in [mW]
    ChargingMode : TPM_CHARGING_MODE - Charge mode
    Description{16} : astr - Designation of the power supply unit

    myDatalogEASY IoT

    Description

    Standard library for the rapidM2M Studio ecosphere

    HARDWARE

    M2EASYIOT:

    boardref:
     

    µINO STYLE

    vextWrite()serialBegin()serialWrite()→ RS485vextWrite()serialBegin()serialWrite()→ RS232sysRead()powerRead()powerWatch()→ POWER MANAGEMENTdoWrite()doMode()→ DIGITAL OUTPUTsvextWrite()uiRead()uiMode()→ UNIVERSAL INPUTsvsensWrite()tempRead()tempMode()→ TEMPERATURE SENSORbuttonWatch()→ SWITCHledWrite()→ LED

    CLASSIC STYLE

    Ext3V3_On()Ext3V3_Off()RS485_Init()RS485_Write()→ RS485Ext3V3_On()Ext3V3_Off()RS232_Init()RS232_Write()→ RS232EasyV3_GetSysValues()PM_GetInfo()PM_BackupInit()→ POWER MANAGEMENTDigOut_Init()DigOut_SetValue()→ DIGITAL OUTPUTsExt3V3_On()Ext3V3_Off()UI_GetValue()UI_ResetCounter()UI_Init()→ UNIVERSAL INPUTsVsens_On()Vsens_Off()Temp_Init()Temp_GetValue()→ TEMPERATURE SENSORSwitch_Init()→ SWITCHLed_Init()Led_On() Led_Off()→ LED

    LID COVER

    M2EASYIOT:

    LidCover_Init(mode, funcidx=-1)

    Initialises the lid reed contact

    mode : s32 - reserved for extensions; must be set to 0
    funcidx : s32 - Index of the public function that should be executed in the event of a state change of the lid reed contact.

    Type of the function (see TLidCover_Callback):
    public func( key);
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TLidCover_Callback(
    public func( key);
    Function to be provided by the device logic developer, that is called when the state of the lid reed contact changes (registered with LidCover_Init() ).
    key : s32 - Indicates which state change called the function
    0 - Housing cover has been opened
    1 - Housing cover has been closed
    LidCover_Close()

    Deactivates the lid reed contact.

    When the housing cover is opened/closed, no action is triggered any more.
    returns : Terror
    OK - if successful
    < OK - if an error occurs

    SYSTEM

    M2EASYIOT:

    EasyV3_GetSysValues(out values[TEasyV3_SysValue], len=sizeof values)

    Reads the last valid values for the "Internal housing temperature" and "Air humidity in the housing" from the system. The interval for determining these values is 10sec. and cannot be changed.

    values : TEasyV3_SysValue - Structure for storing the measurement values
    len : s32 - Size (in cells) of the structure to store the measurement values
    returns : Terror
    >0 - Size (in cells) of the structure used to store the measurement values
    ERROR - if one of the following errors occurs
  • Address and/or length of the values structure is invalid (outside the device logic data memory)
  • One of the measurement values is invalid
    • TEasyV3_SysValue:

    Internal measurement values

    Temp : s32 - Internal housing temperature in [0.1°C]
    RH : s32 - Humidity in the housing in [0.1% rH]
    EasyV3_GetSysValues()

    TEMPERATURE SENSOR

    M2EASYIOT:

    Temp_Init(temp, mode)

    Init and configure external temperature sensing module

    These functions address the external temperature sensor optionally connected to clamps RTD+/RTD-. Use EasyV3_GetSysValues() to read from the internal temperature sensor.
    The temperature is only measured once after this function is called if single conversion mode has been activated (mode = TEMP_MODE_SINGLE_CONV). The measurement value can be read out by the Temp_GetValue() function until the PT100/1000 interface is closed by the Temp_Close() function.
    The temperature is measured at 320ms intervals after this function is called if continuous conversion mode has been activated (mode = TEMP_MODE_CONT_CONV). The Temp_GetValue() function always supplies the last valid temperature value until the PT100/1000 interface is closed by the Temp_Close() function.
    temp : TtempPort - Number of the PT100/1000 interface; is always 0 for the device
    mode : s32
    TEMP_MODE_SINGLE_CONV = 0 - single conversion mode
    The temperature is only measured once after the Temp_Init() function is called.
    TEMP_MODE_CONT_CONV = 1 - continuous conversion mode
    The temperature is measured continuously at 320ms intervals after the Temp_Init() function is called.
    returns : Terror
    >0 - Time in [ms] required to measure the temperature
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    ERROR - if an invalid parameter was transferred
    The energy consumption in continuous conversion mode is significantly higher than in single conversion mode. The lowest level of energy consumption is only achieved once the PT100/1000 interface is closed via the Temp_Close() function. This means that even if the PT100/1000 interface was initialised in single conversion mode, it should be closed as soon as the measurement value is read out.
    Temp_GetValue() Temp_Close()
    Temp_Close(temp)

    Closes the PT100/1000 interface.

    This switches the temperature module to the mode with the lowest energy consumption.
    temp : TtempPort - Number of the PT100/1000 interface; is always 0 on the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    Temp_Init()
    Temp_GetValue(temp, out value)

    Reads the temperature measurement value for the specified PT100/1000 interface from the temperature module.

    temp : TtempPort - Number of the PT100/1000 interface; is always 0 on the device
    value : s32 - Variable to store the temperature measurement value to be read out. The temperature measurement value is saved in the temperature module in [0.1°C].
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    Temp_Init()
    TEMP_NUM_CHANNELS - 1

    Number of temperature sensor interfaces, with which the device is equipped

    TtempPort

    Number of temperature sensor interfaces, ranging from 0 to DP_TEMP_CNT-1

    TEMP_CHANNEL1 = 0 - PT100/1000 interface 1
    Temp_Init()

    DIGITAL OUTPUTs

    M2EASYIOT:

    DigOut_Init(digout, mode, cfg1=-1, cfg2=-1)

    Initialises the isolated switch contact (NO, CC).

    The mode is selected via the "mode" parameter. The meaning of the "cfg1" and "cfg2" parameters is dependent on the selected mode.
    Using "DIGOUT_FREQ" (Frequency output) and "DIGOUT_PWM" (PWM output) modes drastically increases the energy consumption.
    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    mode : s32 - Selection of the mode for the isolated switch contact (NO, CC)
    DIGOUT_OFF - Isolated switch contact deactivated
    DIGOUT_DIG - Digital output
    DIGOUT_FREQ - Frequency output
  • cfg1 - Pulse duty factor: 1...100% (default: 50%)
    • DIGOUT_PWM - PWM output
  • cfg1 - Frequency: 0...1000Hz (default: 100Hz)
    • DIGOUT_IMPULSE_PER_MINUTE - Pulse/min.
  • cfg1 - Pulse duration: Dependent on the sample rate of the universal inputs (default: 100ms)

    • Only a multiple of the sample rate for the universal inputs selected via the UI_SetSampleRate() function can be set for the pulse duration in "Pulse/min." mode. The actual pulse duration is calculated as follows:

    Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI
    DIGOUT_IMPULSE_ONCE - Single output of x pulses
  • cfg1 - Pulse duration: 1...500ms (default: 100ms)
  • cfg2 - Pulse pause: 1...500ms (default: 100ms)
    • cfg1 - see mode, not used if not cited there
    cfg2 - see mode, not used if not cited there
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    DigOut_Close(digout)

    Deactivates the isolated switch contact (NO, CC)

    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    DigOut_SetValue(digout, value)

    Specifies the setpoint for the isolated switch contact (NO, CC).

    The meaning of the "value" parameter is dependent on the mode of the isolated switch contact selected via the DigOut_Init() function.
    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    value - Digout mode dependant
  • DIGOUT_OFF: --
  • DIGOUT_DIG: 0 = LOW (contact open), >0 = HIGH (contact closed)
  • DIGOUT_FREQ: Frequency 1...1000Hz
  • DIGOUT_PWM: PWM 0...100%
  • DIGOUT_IMPULSE_PER_MINUTE: Number of pulses that should be issued per minute
  • DIGOUT_IMPULSE_ONCE: Number of pulses that should be issued
    • returns : Terror
    OK - if successful
    < OK - if an error occurs
    Additional explanation on "Pulse/min." mode (DIGOUT_IMPULSE_PER_MINUTE):

    Note that the maximum number of pulses that can be issued per minute is dependent on the pulse duration specified via the DigOut_Init() function:

    Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI

    Number of pulsesmax = 60,000 ms / (pulse duration + sample rateUI)
    Additional explanation on "Pulse" mode (DIGOUT_IMPULSE_ONCE):

    The time required to issue the specified number of pulses is dependent on the pulse duration and pulse pause specified via the DigOut_Init() function:

    t = number of pulses x (pulse duration + pulse pause)
    TdigoutPort

    Number of the digital output (isolated switch contact), ranging from 0 to DP_DIGOUT_CNT-1

    DIGOUT_CHANNEL1 = 0 - isolated switch contact 1
    DIGOUT_NUM_CHANNELS - 1

    Number of digital outputs, with which the device is equipped

    SENSOR SUPPLY

    M2EASYIOT:

    Vsens_Off()

    Deactivates the switchable sensor supply VOUT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs
    Ext3V3_On()

    Activates the switchable 3,3V supply voltage VEXT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs
    Ext3V3_Off()

    Deactivates the switchable 3,3V supply voltage VEXT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    RS232

    M2EASYIOT:

    RS232_Init(rs232, baudrate, mode, funcidx)

    Initialises the RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    baudrate : s32 - Baud rate to be used. Observe the valid limits for the device being used.
    mode : s32 - bitmask
    Stopbits
    RS232_1_STOPBIT = 0b0000000001 - 1 stop bit
    RS232_2_STOPBIT = 0b0000000010 - 2 stop bits
    Parity
    RS232_PARITY_NONE = 0b0000000000 - no parity
    RS232_PARITY_ODD = 0b0000000100 - uneven parity
    RS232_PARITY_EVEN = 0b0000001000 - even parity
    Databits
    RS232_7_DATABIT = 0b0000000000 - 7 data bits
    RS232_8_DATABIT = 0b0000010000 - 8 data bits
    Flow control
    RS232_FLOW_NONE = 0b0000000000 - no flow control
    RS232_FLOW_RTSCTS = 0b0001000000 - RTS/CTS handshake
    Duplex mode
    RS232_FULL_DUPLEX = 0b0000000000 - full duplex mode
    RS232_HALF_DUPLEX = 0b0100000000 - half duplex mode
    RS485 extension direction control
    RS232_RTS_RS485_DIR = 0b1000000000 - RTS pin is used to switch between sending and receiving
    RTS pin = 0 - Receiver active
    RTS pin = 1 - Transmitter active
    This configuration can be used to control the RS485 Interface Extension
    This mode cannot be used in combination with RTS/CTS handshake.
    The half duplex mode (Bit 8 =1) is activated automatically.
    The constants can also be combined using the "or" conjunction.
    funcidx : s32 - Index of the public function for the RS232 character receipt

    Type of the function (see TRS232_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    TRS232_Callback(
    public func(const data{}, len);
    Function to be provided by the device logic developer, that is called when characters are received via the RS232 interface (registered with RS232_Init() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    RS232_Close(rs232)

    Closes the RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS232_Write(rs232, const data{}, len)

    Sends data via the specified RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes, if successful
    If the number of processed bytes deviates from the passed number of bytes to be sent, the RS232_Write() function must be called again. However, now only the data that could not be processed in the previous function call needs to be passed here.
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS232_Setbuf(rs232, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the RS232 interface from the RAM area reserved for the Device Logic. When this function is called, the system switches from the 256 byte buffers integrated in the firmware to the transferred buffers.

    If necessary, this function may need to be called before the initialisation of the RS232 interface via the RS232_Init() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the RS232 interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the RS232 interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TRS232port

    Number of the RS232 port ranging from 0 to DP_RS232_CNT-1

    RS232_ITF1 = 0 - RS232 interface 1

    RS485

    M2EASYIOT:

    RS485_Init(rs485, baudrate, mode, funcidx)

    Initialises the RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    baudrate : s32 - Baud rate to be used. Observe the valid limits for the device being used.
    mode : s32 - bitmask
    Stopbits
    RS485_1_STOPBIT = 0b000000001 - 1 stop bit
    RS485_2_STOPBIT = 0b000000010 - 2 stop bits
    Parity
    RS485_PARITY_NONE = 0b000000000 - no parity
    RS485_PARITY_ODD = 0b000000100 - uneven parity
    RS485_PARITY_EVEN = 0b000001000 - even parity
    Databits
    RS485_7_DATABIT = 0b000000000 - 7 data bits
    RS485_8_DATABIT = 0b000010000 - 8 data bits
    Duplex mode
    RS485_HALF_DUPLEX = 0b000000000 - half duplex mode
    RS485_FULL_DUPLEX = 0b100000000 - full duplex mode
    Termination resistor
    RS485_120_OHM_NONE = 0b0000000000000000 - no load resistance
    RS485_120_OHM_ACT = 0b0000001000000000 - 120 Ohm load resistance
    The constants can also be combined using the "or" conjunction.
    funcidx : s32 - Index of the public function for the RS485 character receipt

    Type of the function (see TRS485_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    TRS485_Callback(
    public func(const data{}, len);
    Function to be provided by the device logic developer, that is called when characters are received via the RS485 interface (registered with RS485_Init() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    RS485_Close(rs485)

    Closes the RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS485_Write(rs485, const data{}, len)

    Sends data via the specified RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes, if successful
    If the number of processed bytes deviates from the passed number of bytes to be sent, the RS485_Write() function must be called again. However, now only the data that could not be processed in the previous function call needs to be passed here.
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS485_Setbuf(rs485, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the RS485 interface from the RAM area reserved for the Device Logic. When this function is called, the system switches from the 256 byte buffers integrated in the firmware to the transferred buffers.

    If necessary, this function may need to be called before the initialisation of the RS485 interface via the RS485_Init() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the R485 interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the RS485 interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TRS485port

    Number of the RS485 port ranging from 0 to DP_RS485_CNT-1

    RS485_ITF1 = 0 - RS485 interface 1

    BLE

    M2EASYIOT:

    BLE_GetId(id[TBLE_Id], len=sizeof id)

    Returns the information to identify the BLE module installed in the device

    id : TBLE_Id - Structure for storing the information to identify the BLE module installed in the device
    len : s32 - Size (in cells) of the structure to store the information
    returns : s32
    > = 0 - Size (in cells) of the structure used to store the information
    ERROR - if one of the following errors occurs
  • if the address and/or length of the ID structure are invalid (outside the device logic data memory)
  • the BLE module is not ready
    • BLE_Init(funcidx)

    initialises the BLE interface and specifies the function that should be called up if a BLE event has occurred

    The "BLE_EVENT_DEVINFO" event is triggered as soon as the BLE module is ready.
    funcidx : s32 - Index of the public function that is called up if a BLE event has occurred.

    Type of the function (see TBLE_Callback):
    public func(event, connhandle, const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the BLE module is not unlocked on the device
    ERROR - if any other error occurs
    TBLE_Callback(
    public func(event, connhandle, const data{}, len);
    Function to be provided by the device logic developer,
    that is called up if a BLE event has occurred (registered with BLE_Init() ).
    event : BLE_EVENT_x - BLE event that has occurred
    connhandle : s32 - Connection handle of a certain BLE peripheral
    data{} : u8 - Array for which the content is dependent on the type of BLE event:
    BLE_EVENT_SCAN - Information on a BLE peripheral found during a scan process (see TBLE_Scan). This event is triggered if a BLE peripheral was found during scanning (passive) (see BLE_Scan()).
    BLE_EVENT_SCAN_RSP - Information on a BLE peripheral found during a scan process (see TBLE_Scan). This event is triggered if a BLE peripheral was found during scanning (active) (see BLE_Scan()).
    BLE_EVENT_NOTIFY - Content/data of a characteristic for which the notification was activated (see TBLE_Notify). This event is triggered if the software of the BLE peripheral changes the content of a characteristic for which the notification was previously activated.
    BLE_EVENT_READ - Block of required data from a characteristic (see TBLE_Read). This event is triggered if a block of the requested data was received (see BLE_Read()).
    BLE_EVENT_WRITE_RESULT - Information on how the write process on a characteristic was completed (see TBLE_WriteResult). This event is triggered if the data was successfully written in the characteristics of the BLE peripheral or an error occurred during this process (see BLE_Write()).
    BLE_EVENT_READ_RESULT - Information on how the read process on a characteristic was completed (see TBLE_ReadResult). This event is triggered if all of the requested data was received or an error occurred during this process (see BLE_Read()).
    BLE_EVENT_SCAN_FINISHED - Information on how a scan process was completed (see TBLE_ScanFinished). This event is triggered when the scan process is completed (see BLE_Scan()).
    BLE_EVENT_DEVINFO - Information to identify the BLE module installed in the device (see TBLE_DevInfo). This event is triggered if the BLE module has been initialised via BLE_Init() and is ready.
    BLE_EVENT_CONNECT - Information regarding the status change of the connection with a BLE peripheral (see TBLE_Connect). This event is triggered if the connection to a BLE peripheral could be established/disconnected or if an error was triggered (see BLE_Connect() and BLE_Disconnect()).
    BLE_EVENT_ERROR - Information regarding which error has occurred (see TBLE_Error). This event is triggered if an internal error occurs.
    BLE_EVENT_RAWCMD_STRING - String that was sent by the BLE module as a response to the RAW command. This event is triggered if a STRING/ASCII response is available for a RAW command sent via BLE_SendRawCmd() to the BLE module.
    BLE_EVENT_RAWCMD_OK - "OK". This event is triggered if a RAW command sent via BLE_SendRawCmd() to the BLE module has been terminated successfully.
    BLE_EVENT_RAWCMD_ERROR - "ERROR". This event is triggered if a RAW command sent via BLE_SendRawCmd() to the BLE module could not be processed or failed.
    len : s32 - Number of bytes in the array
    BLE_Close()

    Deactivates the BLE interface. In doing so, the connection to the sensors connected at this time is also automatically disconnected.

    returns : Terror
    OK - if successful
    ERROR - if an error occurs
    BLE_GetState()

    Returns the current status of the BLE interface

    returns : BLE_STATE_x - Status of the BLE interface
    BLE_Scan(time = 10, flags = 0)

    Starts the scan process according to the BLE peripherals

    The command works in non-blocking mode. The "BLE_EVENT_SCAN" event (passive scan) or "BLE_EVENT_SCAN_RSP" event (active scan) is triggered every time a BLE peripheral has been found. The "BLE_EVENT_SCAN_FINISHED" event is triggered when the scan process is completed (i.e. the scan duration has expired). Once the scan process is completed, the BLE_GetState() function returns "BLE_STATE_READY" instead of "BLE_STATE_BUSY".
    time : s32 - Scan duration [s]
    flags : s32 - Type of BLE scan
    0 - passive scan (most energy-efficient)
    1 - active scan (scan request)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if another error occurs
    BLE_Connect(addr{6}, itv = -1)

    Establishes the connection to a BLE peripheral

    The command works in non-blocking mode. The "BLE_EVENT_CONNECT" event is triggered if
  • the connection to a BLE peripheral could be established,
  • an existing connection was interrupted or
  • an error occurred when establishing a connection.
    • addr{} : u8 - HW address of the BLE peripheral with which the connection should be established.
    itv : s32 - BLE connection interval in [ms] (i.e. interval at which the data is exchanged) (Valid values: 8...1000 ms)
    returns : s32
    >= 0 - Connection handle of a certain BLE peripheral if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_Disconnect(connhandle = 0)

    Disconnects the connection to a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_CONNECT" event is triggered if
  • the connection to a BLE peripheral could be disconnected,
  • an error occurred when disconnecting the connection.
    • connhandle : s32 - Connection handle of a certain BLE peripheral
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_GetConnState(connhandle = 0)

    Returns the connection status for a certain BLE peripheral

    connhandle : s32 - Connection handle of a certain BLE peripheral
    returns : s32
    >0 - Connected
    0 - Connection disconnected
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR = if one of the following errors occurs
  • invalid handle
  • any other error
    • BLE_Write(connhandle = 0, handle, const data{}, size)

    Writes data in a certain characteristic of a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_WRITE_RESULT" event is triggered if the data was successfully written in the characteristic of the BLE peripheral or an error occurred while the data was being written.
    connhandle : s32 - Connection handle of a certain BLE peripheral
    handle : s32 - Handle of a certain characteristic (currently has to be determined externally)
    data{} : u8 - Array that contains the data to be written in the characteristic
    size : s32 - Number of bytes to be written
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_Read(connhandle = 0, handle)

    Reads data from a certain characteristic of a BLE peripheral

    The BLE peripheral must already be connected
    The command works in non-blocking mode. The "BLE_EVENT_READ" event is triggered every time a block of the requested data has been received. The "BLE_EVENT_READ_RESULT" event is triggered if all of the requested data was received or an error occurred while reading the data.
    connhandle : s32 - Connection handle of a certain BLE peripheral
    handle : s32 - Handle of a certain characteristic (currently has to be determined externally)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_ChgConItv(connhandle = 0, conitv)

    Changes the BLE connection interval (i.e. interval at which the data is exchanged)

    The BLE peripheral must already be connected
    connhandle : s32 - Connection handle of a certain BLE peripheral
    conitv : s32 - BLE connection interval in [ms] (i.e. interval at which the data is exchanged) (Valid values: 8...1000 ms)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    ERROR - if any other error occurs
    BLE_SetScanResponseData(const data{}, size)

    Sets manufacturer specific data which is part of the response when a BLE central performes an active scan.

    data{} : u8 - Array that contains the data for the scan response
    size : s32 - Size of data (in cells)
    returns : s32
    OK - if successful
    BLE_NOT_ACTIVE - if the BLE interface has not been initialised via BLE_Init()
    BLE_BUSY - if the command queue can no longer store any more commands
    BLE_SendRawCmd(cmd{}, cmdlen, timeout=0)

    Sends RAW commands to the BLE module.

    A RAW command is forwarded directly to the BLE module by the firmware. The developer of the device logic is responsible for developing the RAW commands that are suitable for the BLE module (e.g. stop advertising on NRF5x scanner app: "at+advertise=0\r\n").
    The command works in non-blocking mode. Depending on whether the BLE module could process the RAW command, one of the following events is triggered:
  • BLE_EVENT_RAWCMD_STRING: STRING/ASCII response available
  • BLE_EVENT_RAWCMD_OK: Command completed successfully
  • BLE_EVENT_RAWCMD_ERROR: Command failed
    • cmd{} : u8 - Array that contains the RAW commands to be sent
    cmdlen : s32 - Number of bytes that make up the RAW command
    If the BLE module expects ASCII commands (e.g. NRF5x scanner app), then the final '\0' after the RAW command must be added to the RAW command by the user.
    timeout : s32 - Response timeout
    0 - Internal default timeout is used
    >0 - Response timeout in [ms]
    returns : s32
    OK - if successful
    ERROR - if another error occurs
    BLE_Setbuf(rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the BLE interface from the RAM area reserved for the device logic. When this function is called up, the system switches from the 256 bytes buffers integrated in the firmware to the transferred buffers.

    If required, this function must be called via the BLE_Init() function before the BLE interface is initialised.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the BLE interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the BLE interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the BLE module is not released on the device
    ERROR - if an error occurs
    < OK - if another error occurs - see Terror
    TBLE_Id:

    Information to identify the BLE module installed in the device

    In contrast to the information that is contained in the TBLE_DevInfo structure, this information can be called up at any time via the BLE_GetId() function.
    FWVersion : s32 - Version of the application installed on the BLE module
    The minor version is saved in byte 0, the major version is saved in byte 1. e.g. "01v003": Major version = 1, Minor version = 3.
    TBLE_Scan:

    Information regarding a BLE peripheral found during a (passive or active) scan process (used with TBLE_event() callback)

    addr_type : s32 - Type of BLE address
    0 - Public address
    1 - Random static address
    2 - Random private resolvable address
    3 - Random private non-resolvable address
    addr{6} : u8 - HW address
    rssi : s32 - Signal strength [dBm]
    name{32+1} : astr - Advertising name of the peripheral
    msd_len : s32 - Number of bytes saved in "msd"
    msd{32} : u8 - Manufacturer-specific data
    TBLE_ScanFinished:

    Information on how a scan process (passive or active) was completed

    result : s32 - specifies how the scan process was terminated
    OK - Scan process completed successfully
    ERROR - An error occurred
    ERROR-1 - Timeout
    TBLE_Notify:

    Content/data of a characteristic for which the notification was activated

    charHandle : s32 - Handle of a characteristic
    len : s32 - Number of received bytes
    data{BLE_MAXLEN_NOTIFY} : u8 - Array that contains the received data
    TBLE_WriteResult:

    Information on how the write process on a characteristic was completed

    result : s32 - specifies how the write process was terminated
    OK - Write process completed successfully
    ERROR - An error or timeout occurred
    charHandle : s32 - Handle of the characteristic
    len : s32 - Number of written bytes, if successful
    TBLE_Read:

    Block of requested data from a characteristic

    charHandle : s32 - Handle of a characteristic
    offset : s32 - Offset of the received data block within the characteristic
    len : s32 - Number of available bytes in the data array
    data{BLE_MAXLEN_READ} : u8 - Array that contains the received data
    TBLE_ReadResult:

    Information on how the read process on a characteristic was completed

    result : s32 - specifies how the read process was terminated
    OK - Read process completed successfully
    ERROR - An error or timeout occurred
    charHandle : s32 - Handle of the characteristic
    TBLE_DevInfo:

    Information to identify the BLE module installed in the device.

    This information is provided once via the TBLE_event() callback function ("BLE_EVENT_DEVINFO" event) if the BLE module is initialised via BLE_Init().
    chipname{BLE_MAXLEN_CHIPNAME+1} : astr - Ascii, designation of the BLE module (e.g. NRF52)
    appname{BLE_MAXLEN_APPNAME+1} : astr - Ascii, designation of the application installed on the BLE module (e.g. ScannerApp)
    hwrev{BLE_MAXLEN_HWREV+1} : astr - Ascii, HW revision (e.g. "01v001") (reserved for extensions)
    fwrev{BLE_MAXLEN_FWREV+1} : astr - Ascii, FW version (z.B. "02v000") of the application installed on the BLE module
    addr{6} : u8 - HW address (all bytes are zero, if not available)
    TBLE_Connect:

    Information regarding the status change of the connection with a BLE peripheral

    result : s32 - Status of the connection
    1 - disconnected
    0 - connected
    <0 - ERROR
    addr{6} : u8 - HW address of the BLE peripheral
    TBLE_Error:

    Information regarding which error has occurred

    errorcode : Terror
    BLE_EVENT_x:

    Possible BLE events for the callback function TBLE_event()

    BLE_EVENT_SCAN = 0 - BLE Central: Scan information available (passive scan)
    BLE_EVENT_SCAN_RSP = 1 - BLE Central: Scan information available (active scan)
    BLE_EVENT_NOTIFY = 2 - BLE Central: Notification received
    BLE_EVENT_READ = 3 - BLE Central: Read response data available
    BLE_EVENT_WRITE_RESULT = 4 - BLE Central: Write command is terminated
    BLE_EVENT_READ_RESULT = 5 - BLE Central: Read command is terminated
    BLE_EVENT_SCAN_FINISHED = 6 - BLE Central: The scan process is terminated
    BLE_EVENT_DEVINFO = 7 - Device information available (BLE module is ready)
    BLE_EVENT_CONNECT = 8 - BLE Central: Connected to/disconnected from peripheral
    BLE_EVENT_ERROR = 9 - Internal error has occurred
    BLE_EVENT_RAWCMD_STRING = 10 - RAW command: STRING/ASCII response available
    BLE_EVENT_RAWCMD_OK = 11 - RAW command: OK response available (command terminated successfully)
    BLE_EVENT_RAWCMD_ERROR = 12 - RAW command: ERROR response available (command failed)
    BLE_MAX_CONNECTIONS - 5

    Maximum BLE connections

    Maximum number of simultaneous BLE connections
    BLE_STATE_x:

    Status of the BLE interface.

    Return values of the BLE_GetState() function.
    BLE_STATE_OFF = 0 - The BLE interface is switched off
    BLE_STATE_INIT = 1 - Init sequence active, not ready (yet)
    BLE_STATE_READY = 2 - Ready for the receipt of commands
    BLE_STATE_BUSY = 3 - A command is currently being processed
    BLE_MAXLEN_NOTIFY - 256

    Size of the notification data area

    Maximum size (in bytes) of the data area of a notification
    BLE_MAXLEN_READ - 256

    Size of the data area of a read data block

    Maximum size (in bytes) of the data area of a requested data block from a characteristic
    BLE_ERROR_x:

    BLE error codes

    BLE_ERROR_UNKNOWN = 0 - Unspecified internal error
    BLE_ERROR_INIT = 1 - Initialisation error
    BLE_ERROR_IO = 2 - Internal IO error
    BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
    BLE_ERROR_FORCED_DISC = 4 - Forced disconnect error
    BLE_MAXLEN_CHIPNAME - 20

    Max. length of the designation for the BLE module

    BLE_MAXLEN_APPNAME - 20

    Max. length of the designation for the application installed on the BLE module

    BLE_MAXLEN_HWREV - 20

    Max. length for the string that specifies the HW revision

    BLE_MAXLEN_FWREV - 20

    Max. length for the string that specifies the FW revision

    BLE_CHIPNAME_NRF52 - "NRF52"

    Designation of the BLE module installed in the device

    BLE_APPNAME_SCANNER_APP - "ScannerApp"

    Designation of the application installed on the BLE module

    SWITCH

    M2EASYIOT:

    Switch_Init(mode, funcidx=-1)

    Initialises the solenoid switch

    mode : s32 - Selection of whether the solenoid switch is evaluated by the firmware or device logic
    SWITCH_MODE_INTERNAL = 0 - evaluation by the FW
    If the button was pressed and held for 3 sec., a transmission is initiated when the button is released.
    SWITCH_MODE_SCRIPT = 1 - evaluation by the device logic
    In the event of a state change of the button (press or release), the public function, for which the index was transferred to the Switch_Init() function, is called.
    funcidx : s32 - Index of the public function that should be executed in the event of a state change of the button (only necessary if mode=SWITCH_MODE_SCRIPT)

    Type of the function (see TSwitch_Callback):
    public func(key);
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TSwitch_Callback(
    public func( key);
    Function to be provided by the device logic developer, that is called when the state of the button changes (registered with Switch_Init() ).
    key : s32 - Indicates which state change called the function
    0 - Button was released
    1 - Button was pressed
    Switch_Close()

    Deactivates the solenoid switch. An action is no longer initiated when the button is pressed.

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    LED

    M2EASYIOT:

    Led_Init(mode)

    Initialises the two-colour LED

    mode : s32 - Selection of whether the two-colour LED is controlled by the firmware or device logic
    LED_MODE_INTERNAL - The two-colour LED is used to indicate the operating state.
    LED_MODE_SCRIPT - The state of the two-colour LED can be controlled by the Led_On()), Led_Off(), Led_Blink() and Led_Flash() device logic functions.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Close()

    Deactivates the two-colour LED.

    The two-colour LED cannot be controlled by the firmware or the device logic functions.
    returns : Terror
    OK - if successful
    Led_On(bool:red, bool:green)

    The two-colour LED consists of a red and a green LED that can be switched on separately by this function. If both LEDs are switched on simultaneously, the two-colour LED lights up orange.

    red : bool - true: The red LED is switched on.
    green : bool - true: The green LED is switched on.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Off(bool:red, bool:green)

    The two-colour LED consists of a red and a green LED that can be switched off separately by this function.

    red : bool - true: The red LED is switched off
    green : bool - true: The green LED is switched off
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Blink(red, green)

    Enables the two-colour LED to flash (ton = 500ms , toff = 500ms ).

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED flashes orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED flashes until it is deliberately switched off
  • >0 : Number of times the red LED should flash
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED flashes until it is deliberately switched off
  • >0 : Number of times the green LED should flash
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Flash(red, green)

    Enables the two-colour LED to briefly flash every 500ms.

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED briefly flashes orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED briefly flashes at regular intervals until it is deliberately switched off
  • >0 : Number of times the red LED should briefly flash at regular intervals
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED briefly flashes at regular intervals until it is deliberately switched off
  • >0 : Number of times the green LED should briefly flash at regular intervals
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Flicker(red, green)

    Enables the two-colour LED to flicker (ton = 94ms , toff = 31ms ).

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED flickers orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED flickers until it is deliberately switched off
  • >0 : Number of times the red LED should flicker
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED flickers until it is deliberately switched off
  • >0 : Number of times the green LED should flicker
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred

    UNIVERSAL INPUTs

    M2EASYIOT:

    pin-ui:

    Control universal input modes and sample rate, reset counter value and get current value.

    UI_Init(channel, mode, filtertime)

    Initialises an universal input (UI 1 - UI 4). The sample rate for acquiring the measurement value is configured by the UI_SetSampleRate() function. Calling up the UI_SetSampleRate() function is only necessary, if the default sample rate setting of 16Hz (62,5ms) is not suitable for your application.

    The energy consumption increases with each universal input that is initialised.
    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    mode : s32 - Selection of the mode for the universal input
    UI_CHT_SI_NONE - Universal input deactivated
    UI_CHT_SI_DIGITAL - Digital: max. 32V, low <0,99V, high >2,31V, load 10k086
    UI_CHT_SI_DCTR - Counter: min. pulse length 1ms, load 10k086
    UI_CHT_SI_DFREQ - Frequency: 1...1000Hz, 10k086
    UI_CHT_SI_DPWM - PWM: 1...99%, max. 100Hz, min. pulse length 1ms, load 10k086
    UI_CHT_SI_A020MA - 0/4...20mA: Resolution 6,3µA, max. 23,96mA, load 96Ω
    UI_CHT_SI_A002V - 0...2V: Resolution 610µV, max. 2,5V, load 10k086
    UI_CHT_SI_A010V - 0...10V: Resolution 7,97mV, max. 32V, load 4k7
    UI_CHT_SI_DIRECT - Direct (corresponds to 0...2V mode on the device )
    filtertime : s32
    • "Digital", "Counter", "Frequency" and "PWM" modes:

      Time in [ms] during which the signal must remain constant to initiate a level change. Used to suppress brief faults (debouncing).

    • "0/4...20mA", "0...2V", "0...10V" and "direct" modes:

      Time in [ms] during which the analogue signal is averaged for signal smoothing. Used to suppress signal noise.

    returns : Terror
    OK - if successful
    ERROR_NOT_SUPPORTED - if the selected mode is not supported by this universal input
    < OK - if another error occurs
    UI_Close(channel)

    Deactivates an universal input (UI 1 - UI 4).

    The energy consumption decreases with each universal input that is deactivated.
    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    UI_GetValue(channel, out value)

    Reads the last valid measurement value for the specified universal input from the system.

    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    value : s32 - Variable to store the measurement value to be read out. The way in which the measurement value has to be interpreted, is dependent on the universal input mode.
    UI_CHT_SI_NONE - --
    UI_CHT_SI_DIGITAL - Digital: 0 =^ "low", 1 =^ "high"
    UI_CHT_SI_DCTR - Counter reading []
    UI_CHT_SI_DFREQ - Frequency in [Hz]
    UI_CHT_SI_DPWM - PWM in [%]
    UI_CHT_SI_A020MA - 0/4...20mA: Current in [µA]
    UI_CHT_SI_A002V - 0...2V: Voltage in [mV]
    UI_CHT_SI_A010V - 0...10V: Voltage in [mV]
    UI_CHT_SI_DIRECT - direct: Voltage in [mV]
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    UI_SetSampleRate(samplerate)

    Sets the sample rate for the measurement value acquisition at the universal inputs. The specified setting is always valid for all of the universal inputs. Special settings for individual universal inputs are not possible. The default value of the sample rate is 16Hz (62,5ms).

    The energy consumption increases when the sample rate is increased.
    The selected option also influences the possible value range for the pulse duration of the isolated switch contact in "pulse/min." mode.
    samplerate : s32 - Sample rate in [Hz]; only these constants are allowed:
    UI_SAMPLE_RATE_2
    UI_SAMPLE_RATE_4
    UI_SAMPLE_RATE_8
    UI_SAMPLE_RATE_16
    UI_SAMPLE_RATE_32
    UI_SAMPLE_RATE_64
    UI_SAMPLE_RATE_128
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    The sample rate for the universal inputs operated in "Counter", "Frequency" or "PWM" modes is not relevant. You can use the lowest possible value for the sample rate, if you operate all of the universal inputs in these modes and do not operate the isolated switch contact in "pulse/min." mode.
    UI_ResetCounter(channel)

    Resets the counter reading of an universal input that is being operated in "Counter" mode. If no error occurred during this process, the function returns the counter reading value before resetting the counter.

    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    returns : Terror
    >0 - Counter reading before the reset
    ERROR - if an invalid parameter was transferred
    Tui_channel

    Numbers of the universal inputs ranging from 0 up to DP_UI_CNT-1

    UI_CHANNEL1 = 0 - Universal input 1
    UI_CHANNEL2 = 1 - Universal input 2
    UI_CHANNEL3 = 2 - Universal input 3
    UI_CHANNEL4 = 3 - Universal input 4
    UI_NUM_CHANNELS - 4

    Number of universal inputs, with which the device is equipped

    POWER MANAGEMENT

    M2EASYIOT:

    PM_SetChargingMode(mode)

    Sets the charge mode.

    mode : TPM_CHARGING_MODE
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    ERROR-1 - if the rechargeable battery has been marked as defective and can no longer be charged
    PM_BackupInit(funcidx)

    Activates malfunction monitoring for the supply or charging voltage V IN and specifies the function that should be called up in the event of the supply or charging voltage V IN failing.

    funcidx - Index of the public function that should be called up if a failure of the supply or charging voltage V IN has been detected.

    Type of the function (see TPM_Callback):
    public func();
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    TPM_Callback(
    public func();
    Function to be provided by the device logic developer, that is called up if a failure of the supply or charging voltage V IN has been detected (registered with PM_BackupInit() ).
    PM_BackupClose()

    Deactivates malfunction monitoring for the supply or charging voltage V IN

    returns : Terror
    OK - if successful
    PM_GetInfo(info[TPM_Info], len=sizeof info)

    Provides information on the energy source used and power management status

    info : TPM_Info - Structure for storing the information
    len : s32 - Size (in cells) of the structure to store the information
    returns : Terror
    >= OK - used size (in cells) of the structure for storing the information
    ERROR - if an invalid parameter was transferred
    PM_GetCoulombCounter(flags=0)

    Reads the current state of the Coulomb counter (electric charge) that can be used for the application derived from the system's internal Coulomb counter

    flags : s32 - Configuration flags to be set/deleted
    Bit0 - Resetting the Coulomb counter that can be used for the application
  • 0 - no action
  • PM_CC_RESET = 0x00000001 - Counter reset
    • returns : s32 - Depleted electric charge [mAs] since the last reset of the Coulomb counter that can be used for the application
    TPM_CHARGING_MODE:
    PM_CHARGING_OFF = 0 - Charge control deactivated
    PM_CHARGING_NORMAL = 1 - Charge if the state of charge of the rechargeable battery is <50%.
    PM_CHARGING_SOLAR = 2 - Charge continuously, if possible, and the supply or charging voltage V IN is above 16V.
    TPM_Info:

    Information on the energy source used and power management status

    → PM_GetInfo()
    BatteryType : s32 - PSU type
    PM_BATT_TYPE_NONE = 0 - No battery or external power supply
    PM_BATT_TYPE_NORMAL = 1 - Battery, only discharged
    PM_BATT_TYPE_LIIO = 2 - Li-ion rechargeable battery
    Flags : s32 - Power management status
    PM_FLAG_CHARGING = 0x00000001 - Charge control active
    PM_FLAG_BACKUP = 0x00000002 - Supply via internal energy source following failure of V IN (only if V IN monitoring was activated)
    PM_FLAG_ERROR = 0x00000008 - Power management error (does not charge, SoC cannot be determined, because the memory of the power supply unit could not be read, for example)
    PM_FLAG_AKKU_FAULT = 0x00000010 - The rechargeable battery has been marked defective and can no longer be charged.
    VIn : s32 - Supply or charging voltage V IN in [mV]
    VBatt : s32 - Battery or rechargeable battery voltage in [mV]
    SOC : s32 - State of charge in [0.01%]
    PIn : s32 - Power consumption in [mW]
    ChargingMode : TPM_CHARGING_MODE - Charge mode
    Description{16} : astr - Designation of the power supply unit

    EXTERNAL SIM

    M2EASYIOT:

    rM2M_SetExtSimCfg(cfg[TrM2M_SIMCfg], len=sizeof cfg)

    Saves the transferred configuration data for the external SIM card in the device. Setting the configuration data switches to the external SIM card. To switch back to the internal SIM chip, a structure, in which all of the fields are set to 0, must be transferred when setting the configuration data.

    The chargeable feature "Activation code VPN SIM (300539)" must be released to be able to use the external SIM card.
    cfg : TrM2M_SIMCfg - Structure that contains the configuration data for the external SIM card
    len : s32 - Size (in cells) of the structure that contains the configuration data
    returns : Terror
    >0 - Size (in cells) of the structure used to store the configuration data
    ERROR - if the address and/or length of the info structure are invalid (outside the device logic data memory)
    rM2M_GetExtSimCfg(cfg[TrM2M_SIMCfg]=0, len=sizeof cfg)

    Provides the current configuration data stored for the external SIM card.

    cfg : TrM2M_SIMCfg - Structure to store the configuration data saved for the external SIM card
    len : s32 - Size (in cells) of the structure to store the saved configuration data
    returns : Terror
    >0 - Size (in cells) of the structure used to store the configuration data
    ERROR - if one of the following errors occurs:
  • Address and/or length of the cfg structure is invalid (outside the device logic data memory)
  • No valid configuration data available for the external SIM card
    • TrM2M_SIMCfg:

    Configuration data of an external SIM card

    pin{8} : u8 - Pin code for the external SIM card
    apn{40} : astr - Access point (APN) that should be used for the connection
    username{40} : astr - Username to dial up via the access point
    password{40} : astr - Password to dial up via the access point

    myDatalogEASY V3

    Description

    Standard library for the rapidM2M Studio ecosphere

    SENSOR SUPPLY

    M2EASYV3:

    Vsens_On(mode)

    Activates the switchable sensor supply VOUT. The output voltage can be selected via the "mode" parameter.

    mode : s32 - Selection of the output voltage VOUT
    VSENS_15V = 0 - 15V sensor supply voltage
    VSENS_24V = 1 - 24V sensor supply voltage
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    Vsens_Off()

    Deactivates the switchable sensor supply VOUT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs
    Ext3V3_On()

    Activates the switchable 3,3V supply voltage VEXT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs
    Ext3V3_Off()

    Deactivates the switchable 3,3V supply voltage VEXT.

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    M2EASYIOT:

    Vsens_On(mode)

    Activates the switchable sensor supply VOUT. The output voltage (5...24V ) can be selected via the "mode" parameter.

    mode : s32 - Selection of the output voltage VOUT (5000 .. 24000 [mV])
    You can also use the predefined constants for 15V or 24V:
    VSENS_15V = 15000 - 15V sensor supply voltage
    VSENS_24V = 24000 - 24V sensor supply voltage
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    RS232_3V3_On()

    Activates the switchable 3,3V supply voltage VEXT_RS232

    returns : Terror
    OK - if successful
    < OK - if an error occurs
    RS232_3V3_Off()

    Deactivates the switchable 3,3V supply voltage VEXT_RS232

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    HARDWARE

    M2EASYV3:

    boardref:
     

    µINO STYLE

    vextWrite()serialBegin()serialWrite()→ RS485vextWrite()serialBegin()serialWrite()→ RS232sysRead()powerRead()powerWatch()→ POWER MANAGEMENTdoWrite()doMode()→ DIGITAL OUTPUTsvextWrite()uiRead()uiMode()→ UNIVERSAL INPUTsvsensWrite()tempRead()tempMode()→ TEMPERATURE SENSORbuttonWatch()→ SWITCHledWrite()→ LED

    CLASSIC STYLE

    Ext3V3_On()Ext3V3_Off()RS485_Init()RS485_Write()→ RS485Ext3V3_On()Ext3V3_Off()RS232_Init()RS232_Write()→ RS232EasyV3_GetSysValues()PM_GetInfo()PM_BackupInit()→ POWER MANAGEMENTDigOut_Init()DigOut_SetValue()→ DIGITAL OUTPUTsExt3V3_On()Ext3V3_Off()UI_GetValue()UI_ResetCounter()UI_Init()→ UNIVERSAL INPUTsVsens_On()Vsens_Off()Temp_Init()Temp_GetValue()→ TEMPERATURE SENSORSwitch_Init()→ SWITCHLed_Init()Led_On() Led_Off()→ LED

    SYSTEM

    M2EASYV3:

    EasyV3_GetSysValues(out values[TEasyV3_SysValue], len=sizeof values)

    Reads the last valid values for the "Internal housing temperature" and "Air humidity in the housing" from the system. The interval for determining these values is 10sec. and cannot be changed.

    values : TEasyV3_SysValue - Structure for storing the measurement values
    len : s32 - Size (in cells) of the structure to store the measurement values
    returns : Terror
    >0 - Size (in cells) of the structure used to store the measurement values
    ERROR - if one of the following errors occurs
  • Address and/or length of the values structure is invalid (outside the device logic data memory)
  • One of the measurement values is invalid
    • TEasyV3_SysValue:

    Internal measurement values

    Temp : s32 - Internal housing temperature in [0.1°C]
    RH : s32 - Humidity in the housing in [0.1% rH]
    EasyV3_GetSysValues()

    TEMPERATURE SENSOR

    M2EASYV3:

    Temp_Init(temp, mode)

    Init and configure external temperature sensing module

    These functions address the external temperature sensor optionally connected to clamps RTD+/RTD-. Use EasyV3_GetSysValues() to read from the internal temperature sensor.
    The temperature is only measured once after this function is called if single conversion mode has been activated (mode = TEMP_MODE_SINGLE_CONV). The measurement value can be read out by the Temp_GetValue() function until the PT100/1000 interface is closed by the Temp_Close() function.
    The temperature is measured at 320ms intervals after this function is called if continuous conversion mode has been activated (mode = TEMP_MODE_CONT_CONV). The Temp_GetValue() function always supplies the last valid temperature value until the PT100/1000 interface is closed by the Temp_Close() function.
    temp : TtempPort - Number of the PT100/1000 interface; is always 0 for the device
    mode : s32
    TEMP_MODE_SINGLE_CONV = 0 - single conversion mode
    The temperature is only measured once after the Temp_Init() function is called.
    TEMP_MODE_CONT_CONV = 1 - continuous conversion mode
    The temperature is measured continuously at 320ms intervals after the Temp_Init() function is called.
    returns : Terror
    >0 - Time in [ms] required to measure the temperature
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    ERROR - if an invalid parameter was transferred
    The energy consumption in continuous conversion mode is significantly higher than in single conversion mode. The lowest level of energy consumption is only achieved once the PT100/1000 interface is closed via the Temp_Close() function. This means that even if the PT100/1000 interface was initialised in single conversion mode, it should be closed as soon as the measurement value is read out.
    Temp_GetValue() Temp_Close()
    Temp_Close(temp)

    Closes the PT100/1000 interface.

    This switches the temperature module to the mode with the lowest energy consumption.
    temp : TtempPort - Number of the PT100/1000 interface; is always 0 on the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    Temp_Init()
    Temp_GetValue(temp, out value)

    Reads the temperature measurement value for the specified PT100/1000 interface from the temperature module.

    temp : TtempPort - Number of the PT100/1000 interface; is always 0 on the device
    value : s32 - Variable to store the temperature measurement value to be read out. The temperature measurement value is saved in the temperature module in [0.1°C].
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    Temp_Init()
    TEMP_NUM_CHANNELS - 1

    Number of temperature sensor interfaces, with which the device is equipped

    TtempPort

    Number of temperature sensor interfaces, ranging from 0 to DP_TEMP_CNT-1

    TEMP_CHANNEL1 = 0 - PT100/1000 interface 1
    Temp_Init()

    DIGITAL OUTPUTs

    M2EASYV3:

    DigOut_Init(digout, mode, cfg1=-1, cfg2=-1)

    Initialises the isolated switch contact (NO, CC).

    The mode is selected via the "mode" parameter. The meaning of the "cfg1" and "cfg2" parameters is dependent on the selected mode.
    Using "DIGOUT_FREQ" (Frequency output) and "DIGOUT_PWM" (PWM output) modes drastically increases the energy consumption.
    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    mode : s32 - Selection of the mode for the isolated switch contact (NO, CC)
    DIGOUT_OFF - Isolated switch contact deactivated
    DIGOUT_DIG - Digital output
    DIGOUT_FREQ - Frequency output
  • cfg1 - Pulse duty factor: 1...100% (default: 50%)
    • DIGOUT_PWM - PWM output
  • cfg1 - Frequency: 0...1000Hz (default: 100Hz)
    • DIGOUT_IMPULSE_PER_MINUTE - Pulse/min.
  • cfg1 - Pulse duration: Dependent on the sample rate of the universal inputs (default: 100ms)

    • Only a multiple of the sample rate for the universal inputs selected via the UI_SetSampleRate() function can be set for the pulse duration in "Pulse/min." mode. The actual pulse duration is calculated as follows:

    Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI
    DIGOUT_IMPULSE_ONCE - Single output of x pulses
  • cfg1 - Pulse duration: 1...500ms (default: 100ms)
  • cfg2 - Pulse pause: 1...500ms (default: 100ms)
    • cfg1 - see mode, not used if not cited there
    cfg2 - see mode, not used if not cited there
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    DigOut_Close(digout)

    Deactivates the isolated switch contact (NO, CC)

    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    DigOut_SetValue(digout, value)

    Specifies the setpoint for the isolated switch contact (NO, CC).

    The meaning of the "value" parameter is dependent on the mode of the isolated switch contact selected via the DigOut_Init() function.
    digout : TdigoutPort - Number of the digital output (isolated switch contact); is always 0 for the device
    value - Digout mode dependant
  • DIGOUT_OFF: --
  • DIGOUT_DIG: 0 = LOW (contact open), >0 = HIGH (contact closed)
  • DIGOUT_FREQ: Frequency 1...1000Hz
  • DIGOUT_PWM: PWM 0...100%
  • DIGOUT_IMPULSE_PER_MINUTE: Number of pulses that should be issued per minute
  • DIGOUT_IMPULSE_ONCE: Number of pulses that should be issued
    • returns : Terror
    OK - if successful
    < OK - if an error occurs
    Additional explanation on "Pulse/min." mode (DIGOUT_IMPULSE_PER_MINUTE):

    Note that the maximum number of pulses that can be issued per minute is dependent on the pulse duration specified via the DigOut_Init() function:

    Pulse duration = (cfg1/sample rateUI + 1) x sample rateUI

    Number of pulsesmax = 60,000 ms / (pulse duration + sample rateUI)
    Additional explanation on "Pulse" mode (DIGOUT_IMPULSE_ONCE):

    The time required to issue the specified number of pulses is dependent on the pulse duration and pulse pause specified via the DigOut_Init() function:

    t = number of pulses x (pulse duration + pulse pause)
    TdigoutPort

    Number of the digital output (isolated switch contact), ranging from 0 to DP_DIGOUT_CNT-1

    DIGOUT_CHANNEL1 = 0 - isolated switch contact 1
    DIGOUT_NUM_CHANNELS - 1

    Number of digital outputs, with which the device is equipped

    RS232

    M2EASYV3:

    RS232_Init(rs232, baudrate, mode, funcidx)

    Initialises the RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    baudrate : s32 - Baud rate to be used. Observe the valid limits for the device being used.
    mode : s32 - bitmask
    Stopbits
    RS232_1_STOPBIT = 0b0000000001 - 1 stop bit
    RS232_2_STOPBIT = 0b0000000010 - 2 stop bits
    Parity
    RS232_PARITY_NONE = 0b0000000000 - no parity
    RS232_PARITY_ODD = 0b0000000100 - uneven parity
    RS232_PARITY_EVEN = 0b0000001000 - even parity
    Databits
    RS232_7_DATABIT = 0b0000000000 - 7 data bits
    RS232_8_DATABIT = 0b0000010000 - 8 data bits
    Flow control
    RS232_FLOW_NONE = 0b0000000000 - no flow control
    RS232_FLOW_RTSCTS = 0b0001000000 - RTS/CTS handshake
    Duplex mode
    RS232_FULL_DUPLEX = 0b0000000000 - full duplex mode
    RS232_HALF_DUPLEX = 0b0100000000 - half duplex mode
    RS485 extension direction control
    RS232_RTS_RS485_DIR = 0b1000000000 - RTS pin is used to switch between sending and receiving
    RTS pin = 0 - Receiver active
    RTS pin = 1 - Transmitter active
    This configuration can be used to control the RS485 Interface Extension
    This mode cannot be used in combination with RTS/CTS handshake.
    The half duplex mode (Bit 8 =1) is activated automatically.
    The constants can also be combined using the "or" conjunction.
    funcidx : s32 - Index of the public function for the RS232 character receipt

    Type of the function (see TRS232_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    TRS232_Callback(
    public func(const data{}, len);
    Function to be provided by the device logic developer, that is called when characters are received via the RS232 interface (registered with RS232_Init() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    RS232_Close(rs232)

    Closes the RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS232_Write(rs232, const data{}, len)

    Sends data via the specified RS232 interface

    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes, if successful
    If the number of processed bytes deviates from the passed number of bytes to be sent, the RS232_Write() function must be called again. However, now only the data that could not be processed in the previous function call needs to be passed here.
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS232_Setbuf(rs232, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the RS232 interface from the RAM area reserved for the Device Logic. When this function is called, the system switches from the 256 byte buffers integrated in the firmware to the transferred buffers.

    If necessary, this function may need to be called before the initialisation of the RS232 interface via the RS232_Init() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rs232 : TRS232port - Number of the RS232 interface; is always 0 for the device
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the RS232 interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the RS232 interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TRS232port

    Number of the RS232 port ranging from 0 to DP_RS232_CNT-1

    RS232_ITF1 = 0 - RS232 interface 1

    RS485

    M2EASYV3:

    RS485_Init(rs485, baudrate, mode, funcidx)

    Initialises the RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    baudrate : s32 - Baud rate to be used. Observe the valid limits for the device being used.
    mode : s32 - bitmask
    Stopbits
    RS485_1_STOPBIT = 0b000000001 - 1 stop bit
    RS485_2_STOPBIT = 0b000000010 - 2 stop bits
    Parity
    RS485_PARITY_NONE = 0b000000000 - no parity
    RS485_PARITY_ODD = 0b000000100 - uneven parity
    RS485_PARITY_EVEN = 0b000001000 - even parity
    Databits
    RS485_7_DATABIT = 0b000000000 - 7 data bits
    RS485_8_DATABIT = 0b000010000 - 8 data bits
    Duplex mode
    RS485_HALF_DUPLEX = 0b000000000 - half duplex mode
    RS485_FULL_DUPLEX = 0b100000000 - full duplex mode
    Termination resistor
    RS485_120_OHM_NONE = 0b0000000000000000 - no load resistance
    RS485_120_OHM_ACT = 0b0000001000000000 - 120 Ohm load resistance
    The constants can also be combined using the "or" conjunction.
    funcidx : s32 - Index of the public function for the RS485 character receipt

    Type of the function (see TRS485_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    TRS485_Callback(
    public func(const data{}, len);
    Function to be provided by the device logic developer, that is called when characters are received via the RS485 interface (registered with RS485_Init() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    RS485_Close(rs485)

    Closes the RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    returns : Terror
    OK - if successful
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS485_Write(rs485, const data{}, len)

    Sends data via the specified RS485 interface

    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes, if successful
    If the number of processed bytes deviates from the passed number of bytes to be sent, the RS485_Write() function must be called again. However, now only the data that could not be processed in the previous function call needs to be passed here.
    ERROR_FEATURE_LOCKED - if the specified interface on the device is not released
    < OK - if another error occurs
    RS485_Setbuf(rs485, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware with one buffer for sending and one for receiving characters via the RS485 interface from the RAM area reserved for the Device Logic. When this function is called, the system switches from the 256 byte buffers integrated in the firmware to the transferred buffers.

    If necessary, this function may need to be called before the initialisation of the RS485 interface via the RS485_Init() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    rs485 : TRS485port - Number of the RS485 interface; is always 0 for the device
    rxbuf{} : u8 - Static byte array that should be used as a buffer to receive characters via the R485 interface
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as a buffer to send characters via the RS485 interface
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated buffer (256 bytes). The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TRS485port

    Number of the RS485 port ranging from 0 to DP_RS485_CNT-1

    RS485_ITF1 = 0 - RS485 interface 1

    SWITCH

    M2EASYV3:

    Switch_Init(mode, funcidx=-1)

    Initialises the solenoid switch

    mode : s32 - Selection of whether the solenoid switch is evaluated by the firmware or device logic
    SWITCH_MODE_INTERNAL = 0 - evaluation by the FW
    If the button was pressed and held for 3 sec., a transmission is initiated when the button is released.
    SWITCH_MODE_SCRIPT = 1 - evaluation by the device logic
    In the event of a state change of the button (press or release), the public function, for which the index was transferred to the Switch_Init() function, is called.
    funcidx : s32 - Index of the public function that should be executed in the event of a state change of the button (only necessary if mode=SWITCH_MODE_SCRIPT)

    Type of the function (see TSwitch_Callback):
    public func(key);
    returns : Terror
    OK - if successful
    < OK - if an error occurs
    TSwitch_Callback(
    public func( key);
    Function to be provided by the device logic developer, that is called when the state of the button changes (registered with Switch_Init() ).
    key : s32 - Indicates which state change called the function
    0 - Button was released
    1 - Button was pressed
    Switch_Close()

    Deactivates the solenoid switch. An action is no longer initiated when the button is pressed.

    returns : Terror
    OK - if successful
    < OK - if an error occurs

    LED

    M2EASYV3:

    Led_Init(mode)

    Initialises the two-colour LED

    mode : s32 - Selection of whether the two-colour LED is controlled by the firmware or device logic
    LED_MODE_INTERNAL - The two-colour LED is used to indicate the operating state.
    LED_MODE_SCRIPT - The state of the two-colour LED can be controlled by the Led_On()), Led_Off(), Led_Blink() and Led_Flash() device logic functions.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Close()

    Deactivates the two-colour LED.

    The two-colour LED cannot be controlled by the firmware or the device logic functions.
    returns : Terror
    OK - if successful
    Led_On(bool:red, bool:green)

    The two-colour LED consists of a red and a green LED that can be switched on separately by this function. If both LEDs are switched on simultaneously, the two-colour LED lights up orange.

    red : bool - true: The red LED is switched on.
    green : bool - true: The green LED is switched on.
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Off(bool:red, bool:green)

    The two-colour LED consists of a red and a green LED that can be switched off separately by this function.

    red : bool - true: The red LED is switched off
    green : bool - true: The green LED is switched off
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Blink(red, green)

    Enables the two-colour LED to flash (ton = 500ms , toff = 500ms ).

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED flashes orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED flashes until it is deliberately switched off
  • >0 : Number of times the red LED should flash
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED flashes until it is deliberately switched off
  • >0 : Number of times the green LED should flash
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Flash(red, green)

    Enables the two-colour LED to briefly flash every 500ms.

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED briefly flashes orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED briefly flashes at regular intervals until it is deliberately switched off
  • >0 : Number of times the red LED should briefly flash at regular intervals
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED briefly flashes at regular intervals until it is deliberately switched off
  • >0 : Number of times the green LED should briefly flash at regular intervals
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    Led_Flicker(red, green)

    Enables the two-colour LED to flicker (ton = 94ms , toff = 31ms ).

    The two-colour LED consists of a red and a green LED. If both LEDs are used, the two-colour LED flickers orange.
    red : s32
  • -1 : The red LED remains switched off
  • 0 : The red LED flickers until it is deliberately switched off
  • >0 : Number of times the red LED should flicker
    • green : s32
  • -1 : The green LED remains switched off
  • 0 : The green LED flickers until it is deliberately switched off
  • >0 : Number of times the green LED should flicker
    • returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred

    UNIVERSAL INPUTs

    M2EASYV3:

    pin-ui:

    Control universal input modes and sample rate, reset counter value and get current value.

    UI_Init(channel, mode, filtertime)

    Initialises an universal input (UI 1 - UI 4). The sample rate for acquiring the measurement value is configured by the UI_SetSampleRate() function. Calling up the UI_SetSampleRate() function is only necessary, if the default sample rate setting of 16Hz (62,5ms) is not suitable for your application.

    The energy consumption increases with each universal input that is initialised.
    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    mode : s32 - Selection of the mode for the universal input
    UI_CHT_SI_NONE - Universal input deactivated
    UI_CHT_SI_DIGITAL - Digital: max. 32V, low <0,99V, high >2,31V, load 10k086
    UI_CHT_SI_DCTR - Counter: min. pulse length 1ms, load 10k086
    UI_CHT_SI_DFREQ - Frequency: 1...1000Hz, 10k086
    UI_CHT_SI_DPWM - PWM: 1...99%, max. 100Hz, min. pulse length 1ms, load 10k086
    UI_CHT_SI_A020MA - 0/4...20mA: Resolution 6,3µA, max. 23,96mA, load 96Ω
    UI_CHT_SI_A002V - 0...2V: Resolution 610µV, max. 2,5V, load 10k086
    UI_CHT_SI_A010V - 0...10V: Resolution 7,97mV, max. 32V, load 4k7
    UI_CHT_SI_DIRECT - Direct (corresponds to 0...2V mode on the device )
    filtertime : s32
    • "Digital", "Counter", "Frequency" and "PWM" modes:

      Time in [ms] during which the signal must remain constant to initiate a level change. Used to suppress brief faults (debouncing).

    • "0/4...20mA", "0...2V", "0...10V" and "direct" modes:

      Time in [ms] during which the analogue signal is averaged for signal smoothing. Used to suppress signal noise.

    returns : Terror
    OK - if successful
    ERROR_NOT_SUPPORTED - if the selected mode is not supported by this universal input
    < OK - if another error occurs
    UI_Close(channel)

    Deactivates an universal input (UI 1 - UI 4).

    The energy consumption decreases with each universal input that is deactivated.
    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    UI_GetValue(channel, out value)

    Reads the last valid measurement value for the specified universal input from the system.

    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    value : s32 - Variable to store the measurement value to be read out. The way in which the measurement value has to be interpreted, is dependent on the universal input mode.
    UI_CHT_SI_NONE - --
    UI_CHT_SI_DIGITAL - Digital: 0 =^ "low", 1 =^ "high"
    UI_CHT_SI_DCTR - Counter reading []
    UI_CHT_SI_DFREQ - Frequency in [Hz]
    UI_CHT_SI_DPWM - PWM in [%]
    UI_CHT_SI_A020MA - 0/4...20mA: Current in [µA]
    UI_CHT_SI_A002V - 0...2V: Voltage in [mV]
    UI_CHT_SI_A010V - 0...10V: Voltage in [mV]
    UI_CHT_SI_DIRECT - direct: Voltage in [mV]
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    UI_SetSampleRate(samplerate)

    Sets the sample rate for the measurement value acquisition at the universal inputs. The specified setting is always valid for all of the universal inputs. Special settings for individual universal inputs are not possible. The default value of the sample rate is 16Hz (62,5ms).

    The energy consumption increases when the sample rate is increased.
    The selected option also influences the possible value range for the pulse duration of the isolated switch contact in "pulse/min." mode.
    samplerate : s32 - Sample rate in [Hz]; only these constants are allowed:
    UI_SAMPLE_RATE_2
    UI_SAMPLE_RATE_4
    UI_SAMPLE_RATE_8
    UI_SAMPLE_RATE_16
    UI_SAMPLE_RATE_32
    UI_SAMPLE_RATE_64
    UI_SAMPLE_RATE_128
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    The sample rate for the universal inputs operated in "Counter", "Frequency" or "PWM" modes is not relevant. You can use the lowest possible value for the sample rate, if you operate all of the universal inputs in these modes and do not operate the isolated switch contact in "pulse/min." mode.
    UI_ResetCounter(channel)

    Resets the counter reading of an universal input that is being operated in "Counter" mode. If no error occurred during this process, the function returns the counter reading value before resetting the counter.

    channel : Tui_channel - Number of the universal input, starting with 0 for UI 1
    returns : Terror
    >0 - Counter reading before the reset
    ERROR - if an invalid parameter was transferred
    Tui_channel

    Numbers of the universal inputs ranging from 0 up to DP_UI_CNT-1

    UI_CHANNEL1 = 0 - Universal input 1
    UI_CHANNEL2 = 1 - Universal input 2
    UI_CHANNEL3 = 2 - Universal input 3
    UI_CHANNEL4 = 3 - Universal input 4
    UI_NUM_CHANNELS - 4

    Number of universal inputs, with which the device is equipped

    POWER MANAGEMENT

    M2EASYV3:

    PM_SetChargingMode(mode)

    Sets the charge mode.

    mode : TPM_CHARGING_MODE
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    ERROR-1 - if the rechargeable battery has been marked as defective and can no longer be charged
    PM_BackupInit(funcidx)

    Activates malfunction monitoring for the supply or charging voltage V IN and specifies the function that should be called up in the event of the supply or charging voltage V IN failing.

    funcidx - Index of the public function that should be called up if a failure of the supply or charging voltage V IN has been detected.

    Type of the function (see TPM_Callback):
    public func();
    returns : Terror
    OK - if successful
    ERROR - if an invalid parameter was transferred
    TPM_Callback(
    public func();
    Function to be provided by the device logic developer, that is called up if a failure of the supply or charging voltage V IN has been detected (registered with PM_BackupInit() ).
    PM_BackupClose()

    Deactivates malfunction monitoring for the supply or charging voltage V IN

    returns : Terror
    OK - if successful
    PM_GetInfo(info[TPM_Info], len=sizeof info)

    Provides information on the energy source used and power management status

    info : TPM_Info - Structure for storing the information
    len : s32 - Size (in cells) of the structure to store the information
    returns : Terror
    >= OK - used size (in cells) of the structure for storing the information
    ERROR - if an invalid parameter was transferred
    PM_GetCoulombCounter(flags=0)

    Reads the current state of the Coulomb counter (electric charge) that can be used for the application derived from the system's internal Coulomb counter

    flags : s32 - Configuration flags to be set/deleted
    Bit0 - Resetting the Coulomb counter that can be used for the application
  • 0 - no action
  • PM_CC_RESET = 0x00000001 - Counter reset
    • returns : s32 - Depleted electric charge [mAs] since the last reset of the Coulomb counter that can be used for the application
    TPM_CHARGING_MODE:
    PM_CHARGING_OFF = 0 - Charge control deactivated
    PM_CHARGING_NORMAL = 1 - Charge if the state of charge of the rechargeable battery is <50%.
    PM_CHARGING_SOLAR = 2 - Charge continuously, if possible, and the supply or charging voltage V IN is above 16V.
    TPM_Info:

    Information on the energy source used and power management status

    → PM_GetInfo()
    BatteryType : s32 - PSU type
    PM_BATT_TYPE_NONE = 0 - No battery or external power supply
    PM_BATT_TYPE_NORMAL = 1 - Battery, only discharged
    PM_BATT_TYPE_LIIO = 2 - Li-ion rechargeable battery
    Flags : s32 - Power management status
    PM_FLAG_CHARGING = 0x00000001 - Charge control active
    PM_FLAG_BACKUP = 0x00000002 - Supply via internal energy source following failure of V IN (only if V IN monitoring was activated)
    PM_FLAG_ERROR = 0x00000008 - Power management error (does not charge, SoC cannot be determined, because the memory of the power supply unit could not be read, for example)
    PM_FLAG_AKKU_FAULT = 0x00000010 - The rechargeable battery has been marked defective and can no longer be charged.
    VIn : s32 - Supply or charging voltage V IN in [mV]
    VBatt : s32 - Battery or rechargeable battery voltage in [mV]
    SOC : s32 - State of charge in [0.01%]
    PIn : s32 - Power consumption in [mW]
    ChargingMode : TPM_CHARGING_MODE - Charge mode
    Description{16} : astr - Designation of the power supply unit

    EXTERNAL SIM

    M2EASYV3:

    rM2M_SetExtSimCfg(cfg[TrM2M_SIMCfg], len=sizeof cfg)

    Saves the transferred configuration data for the external SIM card in the device. Setting the configuration data switches to the external SIM card. To switch back to the internal SIM chip, a structure, in which all of the fields are set to 0, must be transferred when setting the configuration data.

    The chargeable feature "Activation code VPN SIM (300539)" must be released to be able to use the external SIM card.
    cfg : TrM2M_SIMCfg - Structure that contains the configuration data for the external SIM card
    len : s32 - Size (in cells) of the structure that contains the configuration data
    returns : Terror
    >0 - Size (in cells) of the structure used to store the configuration data
    ERROR - if the address and/or length of the info structure are invalid (outside the device logic data memory)
    rM2M_GetExtSimCfg(cfg[TrM2M_SIMCfg]=0, len=sizeof cfg)

    Provides the current configuration data stored for the external SIM card.

    cfg : TrM2M_SIMCfg - Structure to store the configuration data saved for the external SIM card
    len : s32 - Size (in cells) of the structure to store the saved configuration data
    returns : Terror
    >0 - Size (in cells) of the structure used to store the configuration data
    ERROR - if one of the following errors occurs:
  • Address and/or length of the cfg structure is invalid (outside the device logic data memory)
  • No valid configuration data available for the external SIM card
    • TrM2M_SIMCfg:

    Configuration data of an external SIM card

    pin{8} : u8 - Pin code for the external SIM card
    apn{40} : astr - Access point (APN) that should be used for the connection
    username{40} : astr - Username to dial up via the access point
    password{40} : astr - Password to dial up via the access point

    rapidM2M NRF91

    Description

    Standard library for the rapidM2M Studio ecosphere

    HARDWARE

    NRF91:

    defpinmapping:
    The table below shows the default mapping between the available functions and the pins of the NRF91.
    The "first come, first serve" principle applies to the IO assignment in the device logic.
    Example: If an SPI interface is initialized (using rM2M_SpiInit()), the pins used (CLK, MISO, MOSI) can no longer be used for other purposes (e.g. GPIO). The pins are released again by calling a corresponding close function (rM2M_SpiClose()).
    If the default pin mapping is not suitable, the pin assignment may be changed with following functions:
  • UART - NRF91_UartPinConfig
  • SPI - NRF91_SpiPinConfig
  • I2C - NRF91_I2cPinConfig
  • IRQ - NRF91_IrqPinConfig
  • PWM - NRF91_PwmConfigChannel

    • PinFunction 1Function 2Function 3Function 4
    P0.00reserved
    P0.01reserved
    P0.02reserved
    P0.03reserved
    P0.04GPIO 4UART 0 TXSPI 0 MISOI2C 0 SDA
    P0.05GPIO 5UART 0 RXSPI 0 MOSII2C 0 SCL
    P0.06GPIO 6UART 0 CTSSPI 0 CLK
    P0.07GPIO 7UART 0 RTS
    P0.08GPIO 8UART 1 TXSPI 1 MISOI2C 1 SDA
    P0.09GPIO 9UART 1 RXSPI 1 MOSII2C 1 SCL
    P0.10GPIO 10UART 1 CTSSPI 1 CLK
    P0.11GPIO 11UART 1 RTS
    P0.12GPIO 12
    P0.13GPIO 13Analog IN 0
    P0.14GPIO 14Analog IN 1
    P0.15GPIO 15Analog IN 2
    P0.16GPIO 16Analog IN 3
    P0.17GPIO 17Analog IN 4
    P0.18GPIO 18Analog IN 5
    P0.19GPIO 19Analog IN 6IRQ 0
    P0.20GPIO 20Analog IN 7IRQ 1
    P0.21GPIO 21IRQ 2
    P0.22GPIO 22IRQ 3
    P0.23GPIO 23IRQ 4
    P0.24reserved
    P0.25reserved
    P0.26GPIO 26IRQ 5
    P0.27Sys Button
    P0.28Sys LED
    P0.29GPIO 29PWM 0 CHNL 0
    P0.30GPIO 30PWM 1 CHNL 0
    P0.31GPIO 31PWM 2 CHNL 0

    GPIO

    NRF91:

    NRF91_PinMode(pin, mode)

    Sets the pin mode for a GPIO.

    pin : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    mode : Tnrf_GPIO_MODE - Pin mode to be used for the GPIO
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin is used for another purpose
    ERROR - If another error occurs
    Tnrf_GPIO_MODE: s32

    Pin mode settings for the GPIOs

    NRF91_PIN_MODE_DISABLED = -1 - Deactivate GPIO to minimize power consumption (equals RM2M_GPIO_DISABLED)
    NRF91_PIN_MODE_INPUT = 0 - Input (equals RM2M_GPIO_INPUT)
    NRF91_PIN_MODE_OUTPUT = 1 - Output (equals RM2M_GPIO_OUTPUT)
    NRF91_PIN_MODE_INPUT_PULLUP = 2 - Input with activated pullup resistor
    NRF91_PIN_MODE_INPUT_PULLDOWN = 3 - Input with activated pulldown resistor
    NRF91_PIN_MODE_OUTPUT_OD = 4 - Open-drain output
    NRF91_PINx:

    Available NRF91 pins

    NRF91_PIN0_NA_SPI_FLASH = 0 - GPIO pin 0
    NRF91_PIN1_NA_SPI_FLASH = 1 - GPIO pin 1
    NRF91_PIN2_NA_SPI_FLASH = 2 - GPIO pin 2
    NRF91_PIN3_NA_SPI_FLASH = 3 - GPIO pin 3
    NRF91_PIN4 = 4 - GPIO pin 4
    NRF91_PIN5 = 5 - GPIO pin 5
    NRF91_PIN6 = 6 - GPIO pin 6
    NRF91_PIN7 = 7 - GPIO pin 7
    NRF91_PIN8 = 8 - GPIO pin 8
    NRF91_PIN9 = 9 - GPIO pin 9
    NRF91_PIN10 = 10 - GPIO pin 10
    NRF91_PIN11 = 11 - GPIO pin 11
    NRF91_PIN12 = 12 - GPIO pin 12
    NRF91_PIN13 = 13 - GPIO pin 13
    NRF91_PIN14 = 14 - GPIO pin 14
    NRF91_PIN15 = 15 - GPIO pin 15
    NRF91_PIN16 = 16 - GPIO pin 16
    NRF91_PIN17 = 17 - GPIO pin 17
    NRF91_PIN18 = 18 - GPIO pin 18
    NRF91_PIN19 = 19 - GPIO pin 19
    NRF91_PIN20 = 20 - GPIO pin 20
    NRF91_PIN21 = 21 - GPIO pin 21
    NRF91_PIN22 = 22 - GPIO pin 22
    NRF91_PIN23 = 23 - GPIO pin 23
    NRF91_PIN24_NA_DBG_UART = 24 - GPIO pin 24
    NRF91_PIN25_NA_DBG_UART = 25 - GPIO pin 25
    NRF91_PIN26 = 26 - GPIO pin 26
    NRF91_PIN27_NA_SYS_BUTTON = 27 - GPIO pin 27
    NRF91_PIN28_NA_SYS_LED = 28 - GPIO pin 28
    NRF91_PIN29 = 29 - GPIO pin 29
    NRF91_PIN30 = 30 - GPIO pin 30
    NRF91_PIN31 = 31 - GPIO pin 31
    The pins marked with NA (not applicable) have a dedicated usage (e.g. SysLed) and cannot be used for any other function (e.g. rM2M_GpioDir)
    rM2M_GpioDir(gpio, dir, dirParam=-1)

    Sets the signal direction for a GPIO.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    dir : TrM2M_GPIO_DIR - Signal direction to be used for the GPIO:
    RM2M_GPIO_DISABLED - GPIO deactivated
    RM2M_GPIO_INPUT - Input
    RM2M_GPIO_OUTPUT - Output
    dirParam : RM2M_GPIO_INPUT_xxx/RM2M_GPIO_OUTPUT_xxx - Additional parameter related to configured direction (INPUT or OUTPUT) - OPTIONAL
    In case of RM2M_GPIO_INPUT
    -1Resistor deactivated
    RM2M_GPIO_INPUT_PULLDOWNPull-down resistor activated
    RM2M_GPIO_INPUT_PULLUPPull-up resistor activated
    In case of RM2M_GPIO_OUTPUT
    ValueType of outputInitial output levelInternal resistor
    -1Push-pulllast set output leveldeactivated
    RM2M_GPIO_OUTPUT_LOWPush-pull"low"deactivated
    RM2M_GPIO_OUTPUT_HIGHPush-pull"high"deactivated
    RM2M_GPIO_OUTPUT_ODOpen-drain"high"deactivated
    RM2M_GPIO_OUTPUT_OD_PULLUPOpen-drain"high"pull-up
    RM2M_GPIO_OUTPUT_OSOpen-source"low"deactivated
    RM2M_GPIO_OUTPUT_OS_PULLDOWNOpen-source"low"pull-down
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_GpioSet(gpio, level)

    Set the output level of a GPIO that was configured as an output.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    level : TrM2M_GPIO_LEVEL - Specification of the level to be issued:
    RM2M_GPIO_LOW - Output level set to "low"
    RM2M_GPIO_HIGH - Output level set to "high"
    returns : Terror
    OK - If successful
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an output
    <OK - If an error occurs, see Terror
    rM2M_GpioGet(gpio)

    Read the signal level of a GPIO that was configured as an input.

    gpio : TrM2M_GPIO_PIN - Number of the GPIO, starting with 0 for the first GPIO of the device
    returns : Terror
    RM2M_GPIO_LOW - For "low" at the input
    RM2M_GPIO_HIGH - For "high" at the input
    ERROR_BAD_STATE - If the relevant GPIO was not configured as an input
    <OK - If an error occurs, see Terror
    TrM2M_GPIO_PIN

    Number of GPIO pin, ranging from 0 (= first GPIO of the device) to DP_GPIO_CNT-1

    TrM2M_GPIO_DIR: s32

    Signal direction settings of the GPIOs

    RM2M_GPIO_DISABLED = -1 - Deactivate GPIO to minimise power consumption
  • This turns off any input and output drivers
  • If the device has level shifters, those shifters having all lines disabled become powered down, too.
    • RM2M_GPIO_INPUT = 0 - Turn GPIO to input; be aware that this may drag more power than RM2M_GPIO_DISABLED
    RM2M_GPIO_OUTPUT = 1 - Turn GPIO to output
    TrM2M_GPIO_LEVEL: s32

    Signal levels of the GPIOs

    RM2M_GPIO_LOW = 0 - "low" signal level
    RM2M_GPIO_HIGH = 1 - "high" signal level
    RM2M_GPIO_INPUT_xxx: s32

    Options for Gpio direction INPUT used with rM2M_GpioDir()

    RM2M_GPIO_INPUT_PULLDOWN = 0 - activates the internal pull-down resistor of the CPU for the GPIO
    RM2M_GPIO_INPUT_PULLUP = 1 - activates the internal pull-up resistor of the CPU for the GPIO
    RM2M_GPIO_OUTPUT_xxx: s32

    Options for Gpio direction OUTPUT used with rM2M_GpioDir()

    RM2M_GPIO_OUTPUT_LOW = 0 - Push-pull output with initial level "low"
    RM2M_GPIO_OUTPUT_HIGH = 1 - Push-pull output with initial level "high"
    RM2M_GPIO_OUTPUT_OD = 2 - Open-drain output (Wired-AND) with initial level "high"
    RM2M_GPIO_OUTPUT_OD_PULLUP = 3 - Open-drain output (Wired-AND) with initial level "high" and active pull-up resistor
    RM2M_GPIO_OUTPUT_OS = 4 - Open-source output (Wired-OR) with initial level "low"
    RM2M_GPIO_OUTPUT_OS_PULLDOWN = 5 - Open-source output (Wired-OR) with initial level "low" and active pull-down resistor

    IRQ

    NRF91:

    NRF91_IrqPinConfig(irq, pin)

    Configure/Deconfigure a GPIO for interrupt functionality.

    This function can only be used when the given interrupt is not active (e.i before calling rM2M_IrqInit() or after calling rM2M_IrqClose()). Without using this function the default IRQ pin assignment is used (see NRF91_IRQx_PIN_DEFAULT).
    irq : Tnrf_IRQ - Number of interrupt, starting with 0 for the first interrupt of the device
    pin : TrM2M_GPIO_PIN - Number of the GPIO used for this interrupt, starting with 0 for the first GPIO of the device
    If set to -1 the pin assignment will be removed
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin number is not allowed
    ERROR - If an error occurs
    Tnrf_IRQ

    Number of interrupt, ranging from 0 (= first interrupt of the device) to DP_IRQ_CNT-1

    rM2M_IrqInit(irq, config, funcidx, debounce=0)

    Activates the interrupt functionality of an interruptible pin.

    The number of the interrupt does not correspond to the GPIO pin number. Use the interrupt number specified when assigning the GPIO pin to the interrupt using the NRF91_IrqPinConfig() function.
    irq : TrM2M_IRQ_PIN - Number of interrupt, starting with 0 for the first interrupt of the device
    config : TrM2M_IRQ_xxx - Selection of the edge that should initiate the interrupt and activation of internal pull-up or an internal pull-down resistor:

    Selection of the edges

    RM2M_IRQ_RISING - with rising edges
    RM2M_IRQ_FALLING - with falling edges
    RM2M_IRQ_BOTH - with rising and falling edges

    Configuration of the internal resisters

    RM2M_IRQ_PULLUP - Activates the internal pull-up resistor of the CPU for the GPIO assigned to the interrupt
    RM2M_IRQ_PULLDOWN - Activates the internal pull-down resistor of the CPU for the GPIO assigned to the interrupt
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously. However, for each of the three modes of the edges, either an internal pull-up or an internal pull-down resistor can be activated.
    funcidx : s32 - Index of the public function that should be executed in the event of an interrupt.

    Type of the function (see TrM2M_Irq_Callback):
    public func(pinstate);
    debounce - Debounce time in ms. The interrupt is only triggered if it is pending for longer than the debounce time.
    0 = no debouncing
    returns : Terror
    OK - If successful
    ERROR_ALREADY_SUBSCRIBED - If the number of interrupt has already been initialised
    ERROR_NOT_SUPPORTED - If the pin is used elsewhere (e.g. as a GPIO)
    ERROR - If one of the following errors occurs:
  • Interrupt functionality for this pin not available
  • The function that must be executed in the event of an interrupt is not public.
    • <OK - If another error occurs, see Terror
    TrM2M_IRQ_xxx:

    Edge and resistor configuration for the rM2M_IrqInit() function

    Selection of the edges that should initiate the interrupt

    RM2M_IRQ_RISING = 0 - With rising edges
    RM2M_IRQ_FALLING = 1 - With falling edges
    RM2M_IRQ_BOTH = 2 - With rising and falling edge

    Selection of the internal resistor to be activated for the interruptible pin

    RM2M_IRQ_PULLUP = 0x04 - Activates the internal pull-up resistor
    RM2M_IRQ_PULLDOWN = 0x08 - Activates the internal pull-down resistor
    The internal pull-up and the internal pull-down resistor cannot be activated simultaneously.
    rM2M_IrqClose(irq)

    Deactivates the interrupt functionality of an interruptible pin.

    The number of the interrupt does not correspond to the GPIO pin number. Use the interrupt number specified when assigning the GPIO pin to the interrupt using the NRF91_IrqPinConfig() function.
    irq : TrM2M_IRQ_PIN - Number of interrupt, starting with 0 for the first interrupt of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    NRF91_IRQx_PIN_DEFAULT:

    Default pin assignment for the interrupts.

    NRF91_IRQ0_PIN_DEFAULT = NRF91_PIN12
    NRF91_IRQ1_PIN_DEFAULT = NRF91_PIN19
    NRF91_IRQ2_PIN_DEFAULT = NRF91_PIN20
    NRF91_IRQ3_PIN_DEFAULT = NRF91_PIN21
    NRF91_IRQ4_PIN_DEFAULT = NRF91_PIN22
    NRF91_IRQ5_PIN_DEFAULT = NRF91_PIN23
    TrM2M_Irq_Callback(pinstate)
    public func(pinstate);
    Function to be provided by the device logic developer, that is called up in the event of an interrupt at one of the interruptible pins (registered with rM2M_IrqInit() ).
    pinstate : TrM2M_GPIO_LEVEL - Signal level at the interruptible pin
    TrM2M_IRQ_PIN

    Number of IRQ pin, ranging from 0 (= first interruptible pin of the device) to DP_IRQ_CNT-1

    UART

    NRF91:

    rM2M_UartSetbuf(uart, rxbuf{}, rxlen, txbuf{}, txlen)

    Provides the firmware for the selected UART interface with a sending and/or receiving buffer from the RAM area reserved for the device logic. When this function is called up, the system switches from the two buffers integrated in the firmware to the passed buffers.

    This function must be called up before initialising the UART interface via the rM2M_UartInit() function.
    The buffers "rxbuf" and "txbuf" must be valid during the entire use by the firmware (i.e. they must be defined as a global or static variable).
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    rxbuf{} : u8 - Static byte array that should be used as the receive buffer
    rxlen : s32 - Size of the receiving buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated receiving buffer. The transferred static byte array can then be used by the device logic again.
    txbuf{} : u8 - Static byte array that should be used as the sending buffer
    txlen : s32 - Size of the sending buffer in byte
    If the function is called up again and the size is set to "0" during the process, then the system switches back to the integrated sending buffer. The transferred static byte array can then be used by the device logic again.
    returns : Terror
    OK - If successful
    ERROR - If an error occurs
    rM2M_UartInit(uart, baudrate, mode, funcidx)

    Initialises the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    baudrate : s32 - Baud rate to be used. Please observe the valid limits for the module being used.
    mode : s32 - Bitmask
    Stopbits
    RM2M_UART_1_STOPBIT = 0b0000000001
    RM2M_UART_2_STOPBIT = 0b0000000010
    Parity
    RM2M_UART_PARITY_NONE = 0b0000000000
    RM2M_UART_PARITY_ODD = 0b0000000100
    RM2M_UART_PARITY_EVEN = 0b0000001000
    Databits
    RM2M_UART_7_DATABIT = 0b0000000000
    RM2M_UART_8_DATABIT = 0b0000010000
    Flow control
    RM2M_UART_FLOW_NONE = 0b0000000000 - no flow control
    RM2M_UART_FLOW_RTSCTS = 0b0001000000 - RTS/CTS handshake
    Duplex mode
    RM2M_UART_FULL_DUPLEX = 0b0000000000 - rx and tx at the same time; typ. for RS232
    RM2M_UART_HALF_DUPLEX = 0b0100000000 - rx/tx alteration; typ. for RS485
    RTS direction control
    RM2M_UART_RTS_DIR = 0b1000000000 - RTS pin is used to switch between sending and receiving
    RTS pin = 0 - Receiver active
    RTS pin = 1 - Transmitter active
    This configuration can be used to control a RS485 transceiver in 2-wire mode.
    This mode cannot be used in combination with RTS/CTS handshake.
    The half duplex mode (Bit 8 =1) is activated automatically.
    funcidx : s32 - Index of the public function for the UART character receipt.

    Type of the function (see TUart_Callback):
    public func( const data{}, len);
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If one of the pins required for the UART interface (e.g. RxD) is used elsewhere (e.g. as GPIO)
    <OK - If an error occurs, see Terror
    TUart_Callback(
    public func( const data{}, len);
    Function to be provided by the device logic developer, that is called up when characters are received via the UART interface (registered with rM2M_UartInit() ).
    data{} : u8 - Array that contains the received data
    len : s32 - Number of received bytes
    rM2M_UartClose(uart)

    Closes the UART interface.

    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    returns : Terror
    OK - If successful
    <OK - If an error occurs, see Terror
    rM2M_UartWrite(uart, const data{}, len)

    Sends data via the specified UART interface.

    To read data from the UART interface, use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    data{} : u8 - Array that contains the data to be sent
    len : s32 - Number of bytes to be sent
    returns : Terror
    >=0 - Number of processed bytes if successful
    If the number of processed bytes differs from the transferred number of bytes to be sent, the rM2M_UartWrite () function must be called again. However, only the data that could not be processed during the previous call must be transferred.
    <OK - If an error occurs, see Terror
    rM2M_UartWriteStr
    rM2M_UartWriteStr(const uart, const str{})

    Sends a string via the specified UART interface.

    To read data from the UART interface use the receive callback (see TUart_Callback) specified by rM2M_UartInit().
    uart : TrM2M_UART_PORT - Number of the UART interface, starting with 0 for the first UART interface of the device
    str : astr - ANSI string to be sent, zero terminated
    rM2M_UartWrite
    TrM2M_UART_PORT

    Number of the UART port ranging from 0 (= first UART interface of the device) to DP_UART_CNT-1

    NRF91_UartPinConfig(uart, txpin, rxpin, rtspin=-1, ctspin=-1)

    Configure/Deconfigure the pin assignment for the given UART instance

    This function can only be used when the given UART instance is not active (i.e. before calling rM2M_UartInit() or after calling rM2M_UartClose()). Without using this function the default UART pin assignment is used (see NRF91_UARTx_xxx_PIN_DEFAULT).
    uart : TrM2M_UART_PORT - Number of the UART instance
    txpin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the TX pin
    If set to -1 the pin assignment will be removed
    rxpin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the RX pin
    If set to -1 the pin assignment will be removed
    rtspin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the RTS pin
    If set to -1 the pin assignment will be removed
    The pin is only used if HW Handshake is enabled, see rM2M_UartInit()
    ctspin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the CTS pin
    If set to -1 the pin assignment will be removed
    The pin is only used if HW Handshake is enabled, see rM2M_UartInit()
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin is used for another purpose
    ERROR - If one of the following errors occurs
  • Invalid UART instance number
  • UART already active
  • Invalid GPIO pin
  • Another error occurs
    • NRF91_UARTx_xxx_PIN_DEFAULT:

    Default pin assignment for the UART instances.

    NRF91_UART0_TX_PIN_DEFAULT = NRF91_PIN4
    NRF91_UART0_RX_PIN_DEFAULT = NRF91_PIN5
    NRF91_UART0_CTS_PIN_DEFAULT = NRF91_PIN6
    NRF91_UART0_RTS_PIN_DEFAULT = NRF91_PIN7
    NRF91_UART1_TX_PIN_DEFAULT = NRF91_PIN8
    NRF91_UART1_RX_PIN_DEFAULT = NRF91_PIN9
    NRF91_UART1_CTS_PIN_DEFAULT = NRF91_PIN10
    NRF91_UART1_RTS_PIN_DEFAULT = NRF91_PIN11

    I2C

    NRF91:

    rM2M_I2cInit(i2c, clock, config)

    Initialises the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : s32 - Reserved for extensions
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the I²C interface has already been initialised
    ERROR_NOT_SUPPORTED - If one of the pins required for the I²C interface (e.g. I2C CLK) is used elsewhere (e.g. as GPIO)
    <OK - If another error occurs, see Terror
    rM2M_I2cClose(i2c)

    Closes the I²C interface.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the I²C interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_I2cCom(i2c, addr, data{}, txlen, rxlen)

    Executes an I²C communication. Data is first of all sent and data is then received.

    i2c : TrM2M_I2C_PORT - Number of the I²C interface, starting with 0 for the first I2C interface of the device
    addr : s32 - Address of the I²C slave (Bit7-Bit1, Bit0 unused)
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : TrM2M_I2C_ERROR
    OK - If successful
    RM2M_I2C_NACKERR - If NACK was received during transmission (e.g. incorrect device address, device not responding)
    RM2M_I2C_BUSERR - If a bus error occurs during transmission (e.g. START/STOP placed incorrectly)
    RM2M_I2C_ARBERR - If the arbitration is lost during transmission
    RM2M_I2C_USAGEFAULT - If an internal error occurs
    RM2M_I2C_SWFAULT - If an internal error occurs
    ERROR - If another error occurs, see Terror
    TrM2M_I2C_PORT

    Number of the I²C port ranging from 0 (=first I²C interface of the device) to DP_I2C_CNT-1

    TrM2M_I2C_ERROR: s32

    Error codes of the rM2M_I2cCom() function

    RM2M_I2C_NACKERR = -11 - NACK received during transmission (incorrect device address, device not responding)
    RM2M_I2C_BUSERR = -12 - Bus error during transmission (START/STOP placed incorrectly)
    RM2M_I2C_ARBERR = -13 - Arbitration lost during transmission
    RM2M_I2C_USAGEFAULT = -14 - Internal error
    RM2M_I2C_SWFAULT = -15 - Internal error
    NRF91_I2cPinConfig(i2c, sclpin, sdapin)

    Configure/Deconfigure the pin assignment for the given i2c instance

    This function can only be used when the given I2C instance is not active (i.e. before calling rM2M_I2cInit() or after calling rM2M_I2cClose()). Without using this function the default I2C pin assignment is used (see NRF91_I2Cx_xxx_PIN_DEFAULT).
    i2c : TrM2M_I2C_PORT - Number of the I2C instance
    sclpin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the SCL pin
    If set to -1 the pin assignment will be removed
    sdapin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the SDA pin
    If set to -1 the pin assignment will be removed
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin is used for another purpose
    ERROR - If one of the following errors occurs
  • Invalid I2C instance number
  • I2C instance already active
  • Invalid GPIO pin
  • Another error occurs
    • NRF91_I2Cx_xxx_PIN_DEFAULT:

    Default pin assignment for the I2C instances.

    NRF91_I2C0_SDA_PIN_DEFAULT = NRF91_PIN4
    NRF91_I2C0_SCL_PIN_DEFAULT = NRF91_PIN5
    NRF91_I2C1_SDA_PIN_DEFAULT = NRF91_PIN8
    NRF91_I2C1_SCL_PIN_DEFAULT = NRF91_PIN9

    SPI

    NRF91:

    rM2M_SpiInit(spi, clock, config)

    Initialises the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    clock : s32 - Clock frequency in Hz to be used. Please observe the valid limits for the module being used.
    config : TSPI_MODE - Configuration of clock polarity and clock phase:
    Bit0: Clock polarity
    0 - idle "low"
    1 - idle "high"
    Bit1: Clock phase
    0 - Data are issued at the first edge
    1 - Data are adopted at the first edge
    It is recommended to use the predefined constants "SPI_MODE_0", "SPI_MODE_1", "SPI_MODE_2" or "SPI_MODE_3", as the resulting setting corresponds to the common definitions of SPI modes (see TSPI_MODE).
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    ERROR_ALREADY_SUBSCRIBED - If the SPI interface has already been initialised
    ERROR_NOT_SUPPORTED - If one of the pins required for the SPI interface (e.g. SPI CLK) is used elsewhere (e.g. as GPIO)
    <OK - If another error occurs, see Terror
    RM2M_SPI_CLKPOL - 0b00000001

    Clock polarity: Idle "high"

    Clock polarity is idle "low" if this bit is not set.
    RM2M_SPI_CLKPHA - 0b00000010

    Clock phase: Data are adopted at the first edge

    Data are issued at the first edge if this bit is not set.
    TSPI_MODE

    SPI clock polarity and phase configuration

    SPI_MODE_0 = RM2M_SPI_CLKPHA - idle low, data latch on leading edge
    SPI_MODE_1 = 0 - idle low, data shift on leading edge
    SPI_MODE_2 = RM2M_SPI_CLKPOL | RM2M_SPI_CLKPHA - idle high, data latch on leading edge
    SPI_MODE_3 = RM2M_SPI_CLKPOL - idle high, data shift on leading edge
    rM2M_SpiInit
    RM2M_SPI_CLKPOL, RM2M_SPI_CLKPHA
    rM2M_SpiClose(spi)

    Closes the SPI interface.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    returns : Terror
    OK - If successful
    ERROR - If the number of the SPI interface is invalid
    <OK - If another error occurs, see Terror
    rM2M_SpiCom(spi, data{}, txlen, rxlen)

    Executes an asynchronous SPI communication. Data is first of all sent and data is then received.

    spi : TrM2M_SPI_PORT - Number of the SPI interface, starting with 0 for the first SPI interface of the device
    data{} : u8 - Array in which the data to be sent must initially be saved. Once the data has been sent, the array is used as a memory for the data to be received.
    txlen : s32 - Number of bytes to be sent
    rxlen : s32 - Number of bytes to be received
    returns : Terror
    OK - If successful
    ERROR - If one of te following errors occurs:
  • Number of bytes to be sent >255
  • Number of bytes to be received >255
    • <OK - If another error occurs, see Terror
    TrM2M_SPI_PORT

    Number of the SPI port ranging from 0 (= first SPI interface of the device) to DP_SPI_CNT-1

    NRF91_SpiPinConfig(spi, clkpin, mosipin, misopin)

    Configure/Deconfigure the pin assignment for the given SPI instance

    This function can only be used when the given SPI instance is not active (i.e. before calling rM2M_SpiInit() or after calling rM2M_SpiClose()). Without using this function the default SPI pin assignment is used (see NRF91_SPIx_xxxx_PIN_DEFAULT).
    spi : TrM2M_SPI_PORT - Number of the SPI instance
    clkpin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the Clk pin
    If set to -1 the pin assignment will be removed
    mosipin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the MOSI pin
    If set to -1 the pin assignment will be removed
    misopin : TrM2M_GPIO_PIN - GPIO pin to be assigned as the MISO pin
    If set to -1 the pin assignment will be removed
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin is used for another purpose
    ERROR - If one of the following errors occurs
  • Invalid SPI instance number
  • SPI instance already active
  • Invalid GPIO pin
  • Another error occurs
    • NRF91_SPIx_xxxx_PIN_DEFAULT:

    Default pin assignment for the SPI instances.

    NRF91_SPI0_MISO_PIN_DEFAULT = NRF91_PIN4
    NRF91_SPI0_MOSI_PIN_DEFAULT = NRF91_PIN5
    NRF91_SPI0_CLK_PIN_DEFAULT = NRF91_PIN6
    NRF91_SPI1_MISO_PIN_DEFAULT = NRF91_PIN8
    NRF91_SPI1_MOSI_PIN_DEFAULT = NRF91_PIN9
    NRF91_SPI1_CLK_PIN_DEFAULT = NRF91_PIN10

    SWITCH

    NRF91:

    NRF91_ButtonInit(funcidx=-1)

    Initialises the solenoid switch which is connected to P0.27

    funcidx : s32 - Index of the public function that should be executed in the event of a state change of the solenoid switch.

    Type of the function (see TSwitch_Callback):
    public func( key);
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • No valid index was transferred
  • Button has already been initialized
    • TSwitch_Callback(
    public func( key);
    Function to be provided by the device logic developer, that is called when the state of the button changes (registered with NRF91_ButtonInit() ).
    key : s32 - Indicates which state change called the function
    0 - Button was released
    1 - Button was pressed
    NRF91_ButtonClose()

    Deactivates the solenoid switch. An action is no longer initiated when the button is pressed.

    returns : Terror
    OK - If successful
    ERROR - If an error occurs

    LED

    NRF91:

    NRF91_SetLed(rgb, mode=NRF91_LED_STATIC, count=0)

    Controls the system LED which is connected to P0.28

    Any color with a green component (0x00xx00) turns on the LED.
    rgb : Trgb
    0xRRGGBB - 24bit color code
    CO_GREEN - Turn on the LED
    CO_BLACK - Black, e.g. turn off
    CO_DEFAULT - Give LED control back to firmware (former CO_AUTOMATIC)
    mode : s32 - Optional;
    NRF91_LED_STATIC - default
    NRF91_LED_BLINK - 1s period, 500ms on, 500ms off
    NRF91_LED_FLICKER - 125ms period, 94ms on, 31ms off
    NRF91_LED_FLASH - 500ms period, single 94ms flash on
    count : s32 - Optional;
    0 - Forever (default)
    others - Duration; ignored with NRF91_LED_STATIC
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • Invalid LED mode was transferred (only use NRF91_LED_xxx)
  • Another error occurs
    • Examples
    NRF91_SetLed( CO_GREEN); // turn LED on NRF91_SetLed( CO_BLACK); // turn LED off NRF91_SetLed( CO_GREEN, NRF91_LED_BLINK, 5); // blink LED 5 times NRF91_SetLed( CO_GREEN, NRF91_LED_FLASH); // flash LED forever NRF91_SetLed( CO_DEFAULT); // give back LED to firmware

    ANALOG INPUTs

    NRF91:

    NRF91_AnalogRead(ain)

    Triggers a single ADC conversion for the specified analog channel and returns the result of the measurement in [mV] (max. 3600mV, 12Bit resolution).

    ain : Tain_channel - Number of the analog input
    returns : s32
    >0 - Measured voltage in [mV]
    ERROR_NOT_SUPPORTED - If pin number is not allowed
    ERROR - If an error occurs
    Tain_channel: s32

    Numbers of the analog input channels available at the NRF91, ranging from 0 (=for the first analog input of the device) to DP_AIN_CNT-1

    NRF91_AIN_CHN0 = 0 - Analog input 0
    NRF91_AIN_CHN1 = 1 - Analog input 1
    NRF91_AIN_CHN2 = 2 - Analog input 2
    NRF91_AIN_CHN3 = 3 - Analog input 3
    NRF91_AIN_CHN4 = 4 - Analog input 4
    NRF91_AIN_CHN5 = 5 - Analog input 5
    NRF91_AIN_CHN6 = 6 - Analog input 6
    NRF91_AIN_CHN7 = 7 - Analog input 7
    Every channel corresponds to a dedicated pin, see NRF91_AIN_CHNx_PIN
    NRF91_AIN_CHNx_PIN:

    GPIO pin with analog capabilities

    NRF91_AIN_CHN0_PIN = NRF91_PIN_13
    NRF91_AIN_CHN1_PIN = NRF91_PIN_14
    NRF91_AIN_CHN2_PIN = NRF91_PIN_15
    NRF91_AIN_CHN3_PIN = NRF91_PIN_16
    NRF91_AIN_CHN4_PIN = NRF91_PIN_17
    NRF91_AIN_CHN5_PIN = NRF91_PIN_18
    NRF91_AIN_CHN6_PIN = NRF91_PIN_19
    NRF91_AIN_CHN7_PIN = NRF91_PIN_20

    PWM

    NRF91:

    NRF91_PwmInit(pwm, freq)

    Initializes a PWM instance. Each PWM instance contains 4 PWM channels. The channels can each be assigned to a GPIO using NRF91_PwmConfigChannel().

    pwm : Tpwm_instance - Number of the PWM instance, starting with 0 for the first PWM instance of the device
    freq : s32 - Frequency used for the PWM instance [Hz] (5 - 15000 Hz)
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If any PWM channel pin is used for another purpose (e.g. SPI)
    ERROR - If one of the following errors occurs
  • Invalid PWM instance number was transferred (only use Tpwm_instance)
  • Another error occurs
    • NRF91_PwmConfigChannel(pwm, chnl, pin)

    Assigns/Deassign a GPIO for one of the 4 PWM channels of a PWM instance.

    This function can only be used when the given PWM instance is not active (i.e. before calling NRF91_PwmInit() or after calling NRF91_PwmClose()). Without using this function the default PWM pin assignment is used (see NRF91_PWMx_CHNL0_PIN_DEFAULT).
    pwm : Tpwm_instance - PWM instance (initialized with NRF91_PwmInit())
    chnl : Tpwm_channel - PWM channel to configure
    pin : TrM2M_GPIO_PIN - GPIO pin to be assigned to the PWM channel, starting with 0 for the first GPIO of the device
    If set to -1 the PWM channel will be disabled
    returns : Terror
    OK - If successful
    ERROR_NOT_SUPPORTED - If pin is used for another purpose
    ERROR - If one of the following errors occurs
  • Invalid PWM instance number was transferred (only use Tpwm_instance)
  • PWM instance already active
  • Invalid PWM channel was transferred (only use Tpwm_channel)
  • Invalid GPIO pin was transferred (only use TrM2M_GPIO_PIN)
  • Another error occurs
    • NRF91_PwmSetValue(pwm, chnl, duty)

    Sets the duty cycle for one of the 4 channels of a PWM instance.

    pwm : Tpwm_instance - PWM instance (initialized with NRF91_PwmInit())
    chnl : Tpwm_channel - PWM channel of which the duty cycle is to be set
    duty : s32 - Duty cycle [0.1%] (0.0% - 100.0%)
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • Invalid PWM instance number was transferred (only use Tpwm_instance)
  • Invalid PWM channel was transferred (only use Tpwm_channel)
  • Transferred duty cycle out of range (0.0% - 100.0%)
  • PWM instance was not initialized using NRF91_PwmInit()
  • No GPIO pin was assigned to the PWM channel using NRF91_PwmConfigChannel()
  • Another error occurs
    • NRF91_PwmClose(pwm)

    Closes a PWM instance

    pwm : Tpwm_instance - PWM instance (initialized with NRF91_PwmInit())
    returns : Terror
    OK - If successful
    ERROR - If one of the following errors occurs
  • Invalid PWM instance number was transferred (only use Tpwm_instance)
  • Another error occurs
    • Tpwm_instance: s32

    Numbers of PWM instances available at the NRF91, ranging from 0 (=for the first PWM instance of the device) to DP_PWM_CNT-1

    NRF91_PWM_0 = 0 - PWM instance 0
    NRF91_PWM_1 = 1 - PWM instance 1
    NRF91_PWM_2 = 2 - PWM instance 2
    Tpwm_channel: s32

    Available PWM channels per PWM instance.

    NRF91_PWM_CHNL_PIN0 = 0 - PWM channel 0
    NRF91_PWM_CHNL_PIN1 = 1 - PWM channel 1
    NRF91_PWM_CHNL_PIN2 = 2 - PWM channel 2
    NRF91_PWM_CHNL_PIN3 = 3 - PWM channel 3
    NRF91_PWMx_CHNL0_PIN_DEFAULT:

    Default pin assignment for channel 0 of each PWM instance.

    NRF91_PWM0_CHNL0_PIN_DEFAULT = NRF91_PIN29
    NRF91_PWM1_CHNL0_PIN_DEFAULT = NRF91_PIN30
    NRF91_PWM2_CHNL0_PIN_DEFAULT = NRF91_PIN31

    On this page

    PAWN

    rapidM2M ECOSPHERE

    ~stdlib

    DDE - Data Descriptor

    TUTORIALS

    rapidM2M M22x

    rapidM2M M23x

    BLE & LTE-M Gateway

    myDatalogEASY IoT

    myDatalogEASY V3

    rapidM2M NRF91

    GTCT | Imprint | Privacy Policy | Contact