Send RF quality data to applications

Author: gotthardp

doc/Handlers.md

@@ -44,7 +44,7 @@ release defined in the `rebar.config`:
 
 ## lorawan_application Behaviour
 
-Your module needs to export `init/1`, `handle_join/3` and `handle_rx/4` functions.
+Your module needs to export `init/1`, `handle_join/3` and `handle_rx/5` functions.
 
 ### init(App)
 
@@ -58,17 +58,20 @@ REST API or WebSockets). For more details see
 The `handle_join/3` will be called when a new node joins the network. The function
 shall return either `ok` or `{error, error_description}`.
 
-### handle_rx(DevAddr, App, AppArgs, RxData)
+### handle_rx(DevAddr, App, AppArgs, RxData, RxQ)
+
 The `handle_rx/4` will be called upon reception of a LoRaWAN frame:
   * *DevAddr* is the 4-byte device address
   * *App* is the application name defined in the `sys.config`
   * *AppArgs* is an opaque value assigned to the device
   * *RxData* is the #rxdata{} record with:
+    * *fcnt*
     * *port* number
     * *data* binary
     * *last_lost* flag indicating that the last confirmed response got lost
     * *shall_reply* flag indicating the MAC has to reply to the device even if
       the application sends no data
+  * *RxQ* contains the #rxq{} record with frame reception details
 
 The *last_lost* flag allows the application to decide to send new data instead of
 retransmitting the old data.

include/lorawan.hrl

@@ -4,8 +4,6 @@
 % Distributed under the terms of the MIT License. See the LICENSE file.
 %
 
--record(rxq, {freq, datr, codr, time, tmst, erlst, chan, rfch, stat, rssi, lsnr}).
--record(txq, {freq, datr, codr, tmst, rfch, powe}).
 -record(stat, {time, lati, long, alti, rxnb, rxok, rxfw, ackr, dwnb, txnb}).
 
 -record(ignored_link, {devaddr, mask}).

src/lorawan_admin.erl

@@ -71,9 +71,10 @@ parse_admin(List) ->
                                 Key == devaddr; Key == nwkskey; Key == appskey -> {Key, lorawan_mac:hex_to_binary(Value)};
             ({Key, Value}) when Key == gpspos -> {Key, parse_latlon(Value)};
             ({Key, Value}) when Key == adr_use; Key == adr_set -> {Key, parse_adr(Value)};
+            ({Key, Value}) when Key == rxq -> {Key, ?to_record(rxq, parse_admin(Value))};
             ({Key, Value}) when Key == txdata -> {Key, ?to_record(txdata, parse_admin(Value))};
             ({Key, Value}) when Key == last_join; Key == last_rx; Key == devstat_time;
-                                Key == datetime -> {Key, iso8601:parse(Value)};
+                                Key == time; Key == datetime -> {Key, iso8601:parse_exact(Value)};
             ({Key, Value}) when Key == devstat -> {Key, parse_devstat(Value)};
             (Else) -> Else
         end,
@@ -90,10 +91,13 @@ build_admin(List) ->
                                 Key == frid -> [{Key, lorawan_mac:binary_to_hex(Value)} | A];
             ({Key, Value}, A) when Key == gpspos -> [{Key, build_latlon(Value)} | A];
             ({Key, Value}, A) when Key == adr_use; Key == adr_set -> [{Key, build_adr(Value)} | A];
+            ({Key, Value}, A) when Key == rxq -> [{Key, build_admin(?to_proplist(rxq, Value))} | A];
             ({Key, Value}, A) when Key == txdata -> [{Key, build_admin(?to_proplist(txdata, Value))} | A];
             ({Key, Value}, A) when Key == last_join; Key == last_rx; Key == devstat_time;
-                                Key == datetime -> [{Key, iso8601:format(Value)} | A];
+                                Key == time; Key == datetime -> [{Key, iso8601:format(Value)} | A];
             ({Key, Value}, A) when Key == devstat -> [{Key, build_devstat(Value)} | A];
+            % hide very internal fields
+            ({Key, _Value}, A) when Key == srvtmst -> A;
             (Else, A) -> [Else | A]
         end,
         [], List).

src/lorawan_admin_rxgraph.erl

@@ -51,12 +51,16 @@ get_rxframe(Req, #state{format=rgraph}=State) ->
                 [{id, <<"datr">>}, {label, <<"Data Rate">>}, {type, <<"number">>}],
                 [{id, <<"freq">>}, {label, <<"Frequency (MHz)">>}, {type, <<"number">>}]
                 ]},
-            {rows, lists:map(fun(#rxframe{fcnt=FCnt, region=Region, datr=DatR, freq=Freq}) ->
+            {rows, lists:map(
+                fun(#rxframe{fcnt=FCnt, region=Region, rxq=#rxq{datr=DatR, freq=Freq}}) ->
                     [{c, [
                         [{v, FCnt}],
                         [{v, lorawan_mac_region:datar_to_dr(Region, DatR)}, {f, DatR}],
                         [{v, Freq}]
-                    ]}]
+                    ]}];
+                % if there are some unexpected data, show nothing
+                (_Else) ->
+                    [{c, []}]
                 end, ActRec)
             }
         ],
@@ -72,12 +76,15 @@ get_rxframe(Req, #state{format=qgraph}=State) ->
                 [{id, <<"rssi">>}, {label, <<"RSSI (dBm)">>}, {type, <<"number">>}],
                 [{id, <<"snr">>}, {label, <<"SNR (dB)">>}, {type, <<"number">>}]
                 ]},
-            {rows, lists:map(fun(#rxframe{fcnt=FCnt, rssi=RSSI, lsnr=SNR}) ->
+            {rows, lists:map(
+                fun(#rxframe{fcnt=FCnt, rxq=#rxq{rssi=RSSI, lsnr=SNR}}) ->
                     [{c, [
                         [{v, FCnt}],
                         [{v, RSSI}],
                         [{v, SNR}]
-                    ]}]
+                    ]}];
+                (_Else) ->
+                    [{c, []}]
                 end, ActRec)
             }
         ],

src/lorawan_application_handler.erl

@@ -5,7 +5,7 @@
 %
 -module(lorawan_application_handler).
 
--export([init/0, handle_join/3, handle_rx/4]).
+-export([init/0, handle_join/3, handle_rx/5]).
 -export([store_frame/2, send_stored_frames/2]).
 
 -define(MAX_DELAY, 250). % milliseconds
@@ -33,8 +33,8 @@ invoke_init({App, Module}) when is_atom(Module) ->
 handle_join(DevAddr, App, AppArgs) ->
     invoke_handler(handle_join, App, [DevAddr, App, AppArgs]).
 
-handle_rx(DevAddr, App, AppArgs, RxData) ->
-    invoke_handler(handle_rx, App, [DevAddr, App, AppArgs, RxData]).
+handle_rx(DevAddr, App, AppArgs, RxData, RxQ) ->
+    invoke_handler(handle_rx, App, [DevAddr, App, AppArgs, RxData, RxQ]).
 
 invoke_handler(Fun, App, Params) ->
     {ok, Modules} = application:get_env(plugins),

src/lorawan_application_microchip_mote.erl

@@ -9,7 +9,7 @@
 -module(lorawan_application_microchip_mote).
 -behaviour(lorawan_application).
 
--export([init/1, handle_join/3, handle_rx/4]).
+-export([init/1, handle_join/3, handle_rx/5]).
 
 -include_lib("lorawan_server_api/include/lorawan_application.hrl").
 
@@ -22,14 +22,14 @@ handle_join(_DevAddr, _App, _AppArgs) ->
 
 % the data structure is explained in
 % Lora_Legacy_Mote_Firmware/Includes/Board/MOTEapp.c:520
-handle_rx(DevAddr, _App, _AppArgs, #rxdata{data= <<Light:5/binary, Temp:3/binary>>}) ->
+handle_rx(DevAddr, _App, _AppArgs, #rxdata{data= <<Light:5/binary, Temp:3/binary>>}, _RxQ) ->
     lager:debug("PUSH_DATA ~s ~s",[DevAddr, Light, Temp]),
     % display actual time
     {H, M, S} = time(),
     Time = lists:flatten(io_lib:format('~2..0b:~2..0b:~2..0b', [H, M, S])),
     {send, #txdata{port=2, data=list_to_binary(Time)}};
 
-handle_rx(_DevAddr, _App, _AppArgs, RxData) ->
+handle_rx(_DevAddr, _App, _AppArgs, RxData, _RxQ) ->
     {error, {unexpected_data, RxData}}.
 
 % end of file

src/lorawan_application_semtech_mote.erl

@@ -9,7 +9,7 @@
 -module(lorawan_application_semtech_mote).
 -behaviour(lorawan_application).
 
--export([init/1, handle_join/3, handle_rx/4]).
+-export([init/1, handle_join/3, handle_rx/5]).
 
 -include_lib("lorawan_server_api/include/lorawan_application.hrl").
 
@@ -22,12 +22,12 @@ handle_join(_DevAddr, _App, _AppArgs) ->
 
 % the data structure is explained in
 % https://github.com/Lora-net/LoRaMac-node/blob/master/src/apps/LoRaMac/classA/LoRaMote/main.c#L207
-handle_rx(DevAddr, _App, _AppArgs, #rxdata{port=2, data= <<LED, Press:16, Temp:16, _AltBar:16, Batt, _Lat:24, _Lon:24, _AltGps:16>>}) ->
+handle_rx(DevAddr, _App, _AppArgs, #rxdata{port=2, data= <<LED, Press:16, Temp:16, _AltBar:16, Batt, _Lat:24, _Lon:24, _AltGps:16>>}, _RxQ) ->
     lager:debug("PUSH_DATA ~w ~w ~w ~w",[DevAddr, Press, Temp, Batt]),
     % blink with the LED indicator
     {send, #txdata{port=2, data= <<((LED+1) rem 2)>>}};
 
-handle_rx(_DevAddr, _App, _AppArgs, RxData) ->
+handle_rx(_DevAddr, _App, _AppArgs, RxData, _RxQ) ->
     {error, {unexpected_data, RxData}}.
 
 % end of file

src/lorawan_application_websocket.erl

@@ -6,7 +6,7 @@
 -module(lorawan_application_websocket).
 -behaviour(lorawan_application).
 
--export([init/1, handle_join/3, handle_rx/4]).
+-export([init/1, handle_join/3, handle_rx/5]).
 
 -include_lib("lorawan_server_api/include/lorawan_application.hrl").
 
@@ -20,15 +20,15 @@ handle_join(_DevAddr, _App, _AppArgs) ->
     % accept any device
     ok.
 
-handle_rx(DevAddr, _App, AppArgs, #rxdata{last_lost=true} = RxData) ->
-    send_to_sockets(DevAddr, AppArgs, RxData),
+handle_rx(DevAddr, _App, AppArgs, #rxdata{last_lost=true} = RxData, RxQ) ->
+    send_to_sockets(DevAddr, AppArgs, RxData, RxQ),
     retransmit;
-handle_rx(DevAddr, _App, AppArgs, #rxdata{port=Port} = RxData) ->
-    send_to_sockets(DevAddr, AppArgs, RxData),
+handle_rx(DevAddr, _App, AppArgs, #rxdata{port=Port} = RxData, RxQ) ->
+    send_to_sockets(DevAddr, AppArgs, RxData, RxQ),
     lorawan_application_handler:send_stored_frames(DevAddr, Port).
 
-send_to_sockets(DevAddr, AppArgs, RxData) ->
+send_to_sockets(DevAddr, AppArgs, RxData, RxQ) ->
     Sockets = lorawan_ws_frames:get_processes(DevAddr, AppArgs),
-    [Pid ! {send, DevAddr, AppArgs, RxData} || Pid <- Sockets].
+    [Pid ! {send, DevAddr, AppArgs, RxData, RxQ} || Pid <- Sockets].
 
 % end of file

src/lorawan_handler.erl

@@ -1,22 +1,22 @@
 %
-% Copyright (c) 2016 Petr Gotthard <[email protected]>
+% Copyright (c) 2016-2017 Petr Gotthard <[email protected]>
 % All rights reserved.
 % Distributed under the terms of the MIT License. See the LICENSE file.
 %
 -module(lorawan_handler).
 
 -export([handle_rxpk/3]).
--export([rxpk/4]).
+-export([rxpk/3]).
 
 handle_rxpk(MAC, RxQ, PHYPayload) ->
-    Pid = spawn_link(?MODULE, rxpk, [self(), MAC, RxQ, PHYPayload]),
+    Pid = spawn_link(?MODULE, rxpk, [MAC, RxQ, PHYPayload]),
     {ok, Pid}.
 
-rxpk(Caller, MAC, RxQ, PHYPayload) ->
+rxpk(MAC, RxQ, PHYPayload) ->
     case lorawan_mac:process_frame(MAC, RxQ, PHYPayload) of
         ok -> ok;
         {send, Gateway, TxQ, PHYPayload2} ->
-            lorawan_iface_forwarder:txsend(Caller, Gateway, TxQ, PHYPayload2);
+            lorawan_iface_forwarder:txsend(Gateway, TxQ, PHYPayload2);
         {error, Error} ->
             lager:error("ERROR: ~w", [Error])
     end.

src/lorawan_iface_forwarder.erl

@@ -1,5 +1,5 @@
 %
-% Copyright (c) 2016 Petr Gotthard <[email protected]>
+% Copyright (c) 2016-2017 Petr Gotthard <[email protected]>
 % All rights reserved.
 % Distributed under the terms of the MIT License. See the LICENSE file.
 %
@@ -12,7 +12,7 @@
 
 -export([start_link/1]).
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2, code_change/3]).
--export([txsend/4]).
+-export([txsend/3]).
 
 -include_lib("lorawan_server_api/include/lorawan_application.hrl").
 -include("lorawan.hrl").
@@ -23,9 +23,14 @@ start_link(Port) ->
     gen_server:start_link({global, ?MODULE}, ?MODULE, [Port], []).
 
 init([Port]) ->
-    process_flag(trap_exit, true),
-    {ok, Socket} = gen_udp:open(Port, [binary]),
-    {ok, #state{sock=Socket, pulladdr=dict:new()}}.
+    case gen_udp:open(Port, [binary]) of
+        {ok, Socket} ->
+            process_flag(trap_exit, true),
+            {ok, #state{sock=Socket, pulladdr=dict:new()}};
+        {error, Reason} ->
+            lager:error("Failed to start the packet_forwarder interface: ~w", Reason),
+            {stop, Reason}
+    end.
 
 handle_call(_Request, _From, State) ->
     {stop, {error, unknownmsg}, State}.
@@ -137,22 +142,30 @@ status(MAC, Pk) ->
             lager:error("ERROR: ~w", [Error])
     end.
 
-txsend(Pid, Gateway, TxQ, PHYPayload) ->
+txsend(Gateway, TxQ, PHYPayload) ->
     % TX only supported on radio A
-    Pk = [{txpk, build_txpk(TxQ#txq{rfch=Gateway#gateway.tx_rfch}, PHYPayload)}],
+    Pk = [{txpk, build_txpk(TxQ, Gateway#gateway.tx_rfch, PHYPayload)}],
     % lager:debug("<--- ~w", [Pk]),
-    gen_server:cast(Pid, {send, Gateway#gateway.mac, jsx:encode(Pk)}).
+    gen_server:cast({global, ?MODULE}, {send, Gateway#gateway.mac, jsx:encode(Pk)}).
 
 parse_rxpk(Pk) ->
     Data = base64:decode(proplists:get_value(data, Pk)),
     case proplists:get_value(modu, Pk) of
         <<"LORA">> ->
-            RxQ = ?to_record(rxq, Pk),
-            {RxQ#rxq{erlst=erlang:monotonic_time(milli_seconds)}, Data}
+            RxQ = list_to_tuple([rxq|[get_rxpk_field(X, Pk) || X <- record_info(fields, rxq)]]),
+            {RxQ#rxq{srvtmst=erlang:monotonic_time(milli_seconds)}, Data}
     end.
 
-build_txpk(TxQ, Data) ->
+get_rxpk_field(time, List) ->
+    case proplists:get_value(time, List) of
+        undefined -> undefined;
+        Value -> iso8601:parse_exact(Value)
+    end;
+get_rxpk_field(Field, List) ->
+    proplists:get_value(Field, List).
+
+build_txpk(TxQ, RFch, Data) ->
     ?to_proplist(txq, TxQ) ++
-        [{imme, false}, {modu, <<"LORA">>}, {ipol, true}, {size, byte_size(Data)}, {data, base64:encode(Data)}].
+        [{imme, false}, {modu, <<"LORA">>}, {rfch, RFch}, {ipol, true}, {size, byte_size(Data)}, {data, base64:encode(Data)}].
 
 % end of file

src/lorawan_mac.erl

@@ -231,10 +231,9 @@ reset_link(DevAddr) ->
 store_adr(Link, ADR) -> Link#link{adr_flag_use=ADR}.
 
 store_rxpk(Gateway, Link, RxQ, Frame) ->
-    % store #rxframe{frid, mac, rssi, lsnr, freq, datr, codr, devaddr, fcnt, port, data, region, datetime, devstat}
+    % store #rxframe{frid, mac, rxq, devaddr, fcnt, port, data, region, datetime, devstat}
     mnesia:dirty_write(rxframes, #rxframe{frid= <<(erlang:system_time()):64>>,
-        mac=Gateway#gateway.mac, rssi=RxQ#rxq.rssi, lsnr=RxQ#rxq.lsnr, freq=RxQ#rxq.freq,
-        datr=RxQ#rxq.datr, codr=RxQ#rxq.codr, devaddr=Link#link.devaddr,
+        mac=Gateway#gateway.mac, rxq=RxQ, devaddr=Link#link.devaddr,
         fcnt=Link#link.fcntup, port=Frame#frame.fport, data=Frame#frame.data,
         region=Link#link.region, datetime=calendar:universal_time(), devstat=Link#link.devstat}).
 
@@ -260,7 +259,7 @@ handle_rxpk(Gateway, RxQ, MType, Link, Fresh, Frame)
     end.
 
 handle_uplink(Gateway, RxQ, Confirm, Link, #frame{devaddr=DevAddr,
-        adr_ack_req=ADRACKReq, ack=ACK, fport=FPort, fopts=FOpts, data=RxData}=Frame) ->
+        adr_ack_req=ADRACKReq, ack=ACK, fcnt=FCnt, fport=FPort, fopts=FOpts, data=RxData}=Frame) ->
     {ok, L2, FOptsOut} = lorawan_mac_commands:handle(Link, FOpts),
     ok = mnesia:dirty_write(links, L2#link{last_rx=calendar:universal_time()}),
     ok = store_rxpk(Gateway, L2, RxQ, Frame),
@@ -284,7 +283,7 @@ handle_uplink(Gateway, RxQ, Confirm, Link, #frame{devaddr=DevAddr,
     end,
     % invoke applications
     case lorawan_application_handler:handle_rx(Link#link.devaddr, Link#link.app, Link#link.appid,
-            #rxdata{port=FPort, data=RxData, last_lost=LastLost, shall_reply=ShallReply}) of
+            #rxdata{fcnt=FCnt, port=FPort, data=RxData, last_lost=LastLost, shall_reply=ShallReply}, RxQ) of
         retransmit ->
             {send, Gateway, choose_tx(Link#link.region, RxQ), LostFrame};
         {send, TxData} ->
@@ -300,7 +299,7 @@ choose_tx(Region, RxQ) ->
     Rx1Delay = lorawan_mac_region:regional_config(rx1_delay, Region) / 1000,
     {ok, GwDelay} = application:get_env(gateway_delay),
     % transmit as soon as possible
-    case erlang:monotonic_time(milli_seconds) - RxQ#rxq.erlst of
+    case erlang:monotonic_time(milli_seconds) - RxQ#rxq.srvtmst of
         Small when Small < Rx1Delay - GwDelay ->
             lorawan_mac_region:rx1_rf(Region, RxQ, rx1_delay);
         _Big ->

src/lorawan_mac_region.erl

@@ -8,7 +8,7 @@
 -export([rx1_rf/3, rx2_rf/3, rx2_dr/1, default_adr/1]).
 -export([datar_to_dr/2, freq_range/1, regional_config/2]).
 
--include("lorawan.hrl").
+-include_lib("lorawan_server_api/include/lorawan_application.hrl").
 
 % we calculate in fixed-point numbers
 rx1_rf(Region, RxQ, Window)

src/lorawan_ws_frames.erl

@@ -84,10 +84,10 @@ store_frame0(DevAddr, TxData, State) ->
     lorawan_application_handler:store_frame(DevAddr, TxData),
     {ok, State}.
 
-websocket_info({send, _DevAddr, _AppArgs, #rxdata{data=Data}}, #state{format=raw} = State) ->
+websocket_info({send, _DevAddr, _AppArgs, #rxdata{data=Data}, _RxQ}, #state{format=raw} = State) ->
     {reply, {binary, Data}, State};
-websocket_info({send, DevAddr, _AppArgs, #rxdata{port=Port, data=Data}}, #state{format=json} = State) ->
-    Msg = [{devaddr, lorawan_mac:binary_to_hex(DevAddr)}, {port, Port}, {data, lorawan_mac:binary_to_hex(Data)}],
+websocket_info({send, DevAddr, _AppArgs, RxData, RxQ}, #state{format=json} = State) ->
+    Msg = lorawan_admin:build_admin([{devaddr, DevAddr}, {rxq, RxQ} | ?to_proplist(rxdata, RxData)]),
     {reply, {text, jsx:encode(Msg)}, State};
 websocket_info(Info, State) ->
     lager:warning("Unknown info ~w", [Info]),