utCell.c File Reference

The cell software module handles configuring and running the cell hardware by means of a state engine. More...

#include "uTrack.h"
#include "utCell.h"
#include "utHAL.h"
#include "utRingBuffer.h"
#include "utCommands.h"
#include "utNmeaParser.h"
#include "utServerLocation.h"
#include <stdlib.h>
#include <ctype.h>
#include <limits.h>
#include "utJSON_Factory.h"

Data Structures
struct	CellStateData
struct	operator_type
struct	APNType
struct	APNConfig
struct	CellConfig

Macros
#define	LEN_MODEL   15
	maximum string length for the cell chip model name.
#define	LEN_VERSION   20
	maximum string length for the cell chip model version.
#define	TELSTRA_AUTOBAND_2G   5
	The 2G autoband setting for the Telstra cell chips.
#define	TELSTRA_AUTOBAND_3G   3
	The 3G autoband setting for the Telstra cell chips.
#define	SOFT_RESET_DELAY_POWER_ON_TIME   5
#define	MAX_SHUTDOWN_ATTEMPTS   3
#define	CELL_RX_BUFFER_SIZE   1024
#define	CELL_TX_BUFFER_SIZE   1024
#define	CELL_ENCODE_BUFFER_SIZE   CELL_TX_BUFFER_SIZE
#define	RESET_CONNECTION_ERROR_COUNT_SECONDS   60
#define	POST_SIM_FAILURE_COUNT_THRESHOLD   10
#define	SERVICE_2G   12
#define	SERVICE_3G   22
#define	SERVICE_LTE   28
#define	SERVICE_3G_LTE   31
#define	SERVICE_ALL   25
#define	RESPONSE_BUFFER_LENGTH   1024
#define	SIG_STRENGTH_LEN   128
#define	FILE_BUFFER_SIZE   100
#define	CELL_INTERFACE_NAME   "CELL"
#define	NUMBER_APN_FILES   2

Typedefs
typedef void(*	FStateHandler) (u32 now)

Enumerations
enum	CellConnectState {   CELL_OFF = 0 , INIT_BUFFER , FIRST_COMMAND , MODEL ,   VERSION , GET_IMEI , SET_SPEED , SET_USER_ID ,   SET_PASSWORD , SIM_SETUP , SIM_CHECK , GET_APN ,   SET_OPERATOR , SET_SERVICE , SET_BAND , SIM_CHECK_POST_SETUP ,   WAITING_ON_REG , DEFINING_CONTEXT , SOCKET_CONFIG , QUERY_ACTIVATE ,   ACTIVATE_GPRS , AWAITING_CONNECTION_INFO , GET_DNS_IP , OPEN_CONNECTION ,   CONNECTED , CLOSE_CONNECTION , SOCKET_STATUS_ON_CLOSE , SHUT_SOCKET ,   CHECK_IS_ALIVE , CHECK_SIGNAL_STRENGTH , OPEN_CONNECTION_FOR_HTTP_REQ , GETTING ,   FATAL , MAX_CELL_STATE }
enum	CellFunction {   WAITING_RESPONSE , WAITING_BEFORE_SEND , SENDING_DATA , DATA_TO_SEND ,   IDLE }
enum	CellResponse {   OK = 0 , ERROR_RETRY = 1 , ERROR_RESET = 2 , NO_RESPONSE = 3 ,   UNK_RESPONSE = 4 }
enum	CellOperatorFunction { SCAN , SET_AUTO , SET_ID , DO_NOTHING }
enum	CellStatus { CELL_UNKNOWN , CELL_HAS_NO_SIM , CELL_HAS_BEEN_CONNECTED , CELL_IS_CONNECTED }
enum	APNGET {   SEARCHING_FOR_MCC = 0 , SEARCHING_FOR_MNC , SEARCHING_FOR_APN , SEARCHING_FOR_USER ,   SEARCHING_FOR_PASS , SEARCHING_FOR_TYPE , DEFINING_TYPES , SEARCH_COMPLETE ,   APN_ERROR }
enum	CHAR4SEARCH {   char1 , char2 , char3 , char4 ,   equals , opening , searching }
enum	PowerOnState {   PW_IDLE_ON , PW_SHUTDOWN , PW_POWER_UP_DELAY , PW_MODULE_POWER_UP ,   PW_MODULE_POWER_UP_LINE_LOW , PW_MODULE_POWER_UP_REQUESTING_PWRMON_STATUS , PW_PRE_AT_DELAY , PW_SOFT_RESET ,   PW_HARD_RESET , PW_WAITING_ON_VOLTAGE }

Functions
bool	utCell_Notify (UT_DeviceMessage state)
void	utCell_PowerMon (bool isPowered)
void	utCell_ONOFFLine (bool isHigh)
bool	utCell_IsConnected (void)
bool	utCell_HasEverBeenConnected (void)
bool	utCell_IsOn (void)
void	utCell_OnOff (bool isOn, bool stayOn)
void	utCell_SoftReset (void)
void	utCell_HardReset (void)
void	utCell_ConnectInternal (bool connect)
u32	utCell_BytesToSend (void)
void	CheckUART1Pins ()

Variables
CHAR4SEARCH	SearchState = char1
const u8	cid = 1

Detailed Description

The cell software module handles configuring and running the cell hardware by means of a state engine.

See also utServerLocation.c , which handles DNS and IP parsing and selection.

Author

George Sealy

Oscar Key

Date

23/05/2011

Copyright

2011, Igtimi Ltd., all rights reserved.

Macro Definition Documentation

CELL_RX_BUFFER_SIZE

#define CELL_RX_BUFFER_SIZE   1024

The size of the UART receive buffer between the CPU and the cell hardware module.

CELL_TX_BUFFER_SIZE

#define CELL_TX_BUFFER_SIZE   1024

The size of the UART transmit buffer between the CPU and the cell hardware module.

MAX_SHUTDOWN_ATTEMPTS

#define MAX_SHUTDOWN_ATTEMPTS   3

The number of times to try shutting down before resorting to a reset.

POST_SIM_FAILURE_COUNT_THRESHOLD

#define POST_SIM_FAILURE_COUNT_THRESHOLD   10

The number of times the cell module should loop through the post sim check states before resetting

RESPONSE_BUFFER_LENGTH

#define RESPONSE_BUFFER_LENGTH   1024

The length, in bytes, of the response buffer for handling responses and events from the cell module. Must be at least 129 characters for parsing the DNS query lines. Must be at least 110 or so for #MONI commands.

SERVICE_2G

#define SERVICE_2G   12

The code for cell service 2G only selection.

SERVICE_3G

#define SERVICE_3G   22

The code for cell service 3G only selection.

SERVICE_ALL

#define SERVICE_ALL   25

The code for cell service multiple selection.

SIG_STRENGTH_LEN

#define SIG_STRENGTH_LEN   128

The length, in bytes, of the response buffer for storing #MONI info for logging reasons.

SOFT_RESET_DELAY_POWER_ON_TIME

#define SOFT_RESET_DELAY_POWER_ON_TIME   5

The number of seconds the module should wait after powering down, before powering up after a soft reset

Typedef Documentation

FStateHandler

typedef void(* FStateHandler) (u32 now)

The handler, run at intervals, for a given state.

Enumeration Type Documentation

CellConnectState

enum CellConnectState

The state list for the cell state engine. See the relevant flow chart.

CellFunction

enum CellFunction

The function, or sub-state, within a given state at any point in time.

CellResponse

enum CellResponse

The last response received from the cell hardware. Note that it can be reset in various cases

Todo:

List said cases

Function Documentation

utCell_BytesToSend()

u32 utCell_BytesToSend

(

void

)

Returns

The number of bytes waiting to be transmitted by the appropriate UART.

utCell_ConnectInternal()

void utCell_ConnectInternal

(

bool

connect

)

Connect directs the cell state engine to connect (when it has the opportunity to do so) or disconnect.

Parameters

connect

Whether to connect or disconnect.

utCell_HardReset()

void utCell_HardReset

(

void

)

HardReset resets the cell module using a hardware line dedicated to this purpose. It is typically only used if SoftReset fails (e.g. if communication over the I2C bus has crashed).

utCell_HasEverBeenConnected()

bool utCell_HasEverBeenConnected

(

void

)

HasEverBeenConnected is used for determining whether or not the cell has ever had a data connection to a uServe instance/

Returns

Whether or not the cell has ever had a data connection to a server somewhere.

utCell_IsConnected()

bool utCell_IsConnected

(

void

)

IsConnected is used for determining whether or not the cell has a data connection to a uServe instance/

Returns

Whether or not the cell has a data connection to a server somewhere.

utCell_IsOn()

bool utCell_IsOn

(

void

)

IsOn is used for determining whether or not the cell module is powered on/

Returns

Whether or not the cell module is powered on.

utCell_Notify()

bool utCell_Notify

(

UT_DeviceMessage

state

)

The Notify function passes a message to the software module, informing it of expected module state. It returns a value that is considered a response to a query about the specified state.

Parameters

state

A state message.

Returns

Whether or not this software module is in the desired state.

utCell_OnOff()

void utCell_OnOff	(	bool	isOn,
		bool	stayOn
	)

OnOff turns the cell on or off.

Parameters

isOn	The desired power state for the cell to be in.
stayOn	Whether the cell hardware should remain powered after the software is "turned off".

utCell_PowerMon()

void utCell_PowerMon

(

bool

isPowered

)

PowerMon is called when a PIC event concerning the power to the cell hardware occurs. If the battery voltage is below the cutoff threshold of 3.4V, the cell will be shutdown to conserve power.

Parameters

isPowered

Whether or not the cell hardware has power.

utCell_SoftReset()

void utCell_SoftReset

(

void

)

SoftReset resets the cell module by attempting a normal shutdown and power off followed by a powerup.