simcom-sim7080.h File Reference

Simcom SIM7080 modem public API header file. More...

#include <zephyr/types.h>
#include <stdint.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	sim7080_gnss_data
	Sim7080 gnss data structure. More...
struct	sim7080_sms
	Buffer structure for sms. More...
struct	sim7080_sms_buffer
	Buffer structure for sms reads. More...
struct	sim7080_ue_sys_info_gsm
	Sim7080 ue system information structure for gsm. More...
struct	sim7080_ue_sys_info_lte
	Sim7080 ue system information structure for LTE. More...
struct	sim7080_ue_sys_info
	Sim7080 ue system information structure. More...

Macros
#define	SIM7080_GNSS_DATA_UTC_LEN   20
	Maximum Length of GNSS UTC data.
#define	SIM7080_SMS_MAX_LEN   160
	Maximum SMS length.
#define	SIM7080_UE_SYS_INFO_BAND_SIZE   32
	Maximum UE system information band size.
#define	SIM7080_DNS_MAX_RECOUNT   10
	Maximum number of DNS retries.
#define	SIM7080_DNS_MAX_TIMEOUT_MS   60000
	Maximum timeout for DNS queries in milliseconds.

Enumerations
enum	sim7080_state {   SIM7080_STATE_INIT = 0 , SIM7080_STATE_IDLE , SIM7080_STATE_NETWORKING , SIM7080_STATE_GNSS ,   SIM7080_STATE_OFF }
	Sim7080 modem state. More...
enum	sim7080_sms_stat {   SIM7080_SMS_STAT_REC_UNREAD = 0 , SIM7080_SMS_STAT_REC_READ , SIM7080_SMS_STAT_STO_UNSENT , SIM7080_SMS_STAT_STO_SENT ,   SIM7080_SMS_STAT_ALL }
	Possible sms states in memory. More...
enum	sim7080_ftp_rc { SIM7080_FTP_RC_OK = 0 , SIM7080_FTP_RC_FINISHED , SIM7080_FTP_RC_ERROR }
	Possible ftp return codes. More...
enum	sim7080_ue_sys_mode { SIM7080_UE_SYS_MODE_NO_SERVICE , SIM7080_UE_SYS_MODE_GSM , SIM7080_UE_SYS_MODE_LTE_CAT_M1 , SIM7080_UE_SYS_MODE_LTE_NB_IOT }
	UE system mode. More...
enum	sim7080_ue_op_mode {   SIM7080_UE_OP_MODE_ONLINE , SIM7080_UE_OP_MODE_OFFLINE , SIM7080_UE_OP_MODE_FACTORY_TEST_MODE , SIM7080_UE_OP_MODE_RESET ,   SIM7080_UE_OP_MODE_LOW_POWER_MODE }
	UE operating mode. More...

Functions
enum sim7080_state	mdm_sim7080_get_state (void)
	Get the current state of the modem.
int	mdm_sim7080_power_on (void)
	Power on the Sim7080.
int	mdm_sim7080_power_off (void)
	Power off the Sim7080.
void	mdm_sim7080_force_reset (void)
	Forcefully reset the modem by pulling pwrkey for 15 seconds.
int	mdm_sim7080_start_network (void)
	Activates the network operation mode of the modem.
int	mdm_sim7080_stop_network (void)
	Stops the networking operation mode of the modem.
int	mdm_sim7080_start_gnss (void)
	Starts the modem in gnss operation mode.
int	mdm_sim7080_start_gnss_xtra (void)
	Starts the modem in gnss operation mode with xtra functionality.
int	mdm_sim7080_stop_gnss (void)
	Stops the modem gnss operation mode.
int	mdm_sim7080_download_xtra (uint8_t server_id, const char *f_name)
	Download the XTRA file for assisted gnss.
int	mdm_sim7080_query_xtra_validity (int16_t *diff_h, int16_t *duration_h, struct tm *inject)
	Query the validity of the XTRA file.
int	mdm_sim7080_query_gnss (struct sim7080_gnss_data *data)
	Query gnss position form the modem.
const char *	mdm_sim7080_get_manufacturer (void)
	Get the sim7080 manufacturer.
const char *	mdm_sim7080_get_model (void)
	Get the sim7080 model information.
const char *	mdm_sim7080_get_revision (void)
	Get the sim7080 revision.
const char *	mdm_sim7080_get_imei (void)
	Get the sim7080 imei number.
const char *	mdm_sim7080_get_iccid (void)
	Get the sim7080 iccid number.
int	mdm_sim7080_read_sms (struct sim7080_sms_buffer *buffer)
	Read sms from sim module.
int	mdm_sim7080_delete_sms (uint16_t index)
	Delete a sms at a given index.
int	mdm_sim7080_set_gpio (int gpio, int level)
	Set the level of one of the module's GPIO pins.
int	mdm_sim7080_ftp_get_start (const char *server, const char *user, const char *passwd, const char *file, const char *path)
	Start a ftp get session.
int	mdm_sim7080_ftp_get_read (char *dst, size_t *size)
	Read data from a ftp get session.
int	mdm_sim7080_get_battery_charge (uint8_t *bcs, uint8_t *bcl, uint16_t *voltage)
	Read voltage, charge status and battery connection level.
int	mdm_sim7080_get_ue_sys_info (struct sim7080_ue_sys_info *info)
	Read the ue system information.
int	mdm_sim7080_get_local_time (struct tm *t)
	Get the local time of the modem.
int	mdm_sim7080_dns_set_lookup_params (uint8_t recount, uint16_t timeout)
	Set the dns query lookup parameters.
void	mdm_sim7080_dns_get_lookup_params (uint8_t *recount, uint16_t *timeout)
	Get the dns query lookup parameters.

Detailed Description

Simcom SIM7080 modem public API header file.

Copyright (C) 2021 metraTec GmbH

SPDX-License-Identifier: Apache-2.0

Macro Definition Documentation

SIM7080_DNS_MAX_RECOUNT

#define SIM7080_DNS_MAX_RECOUNT   10

Maximum number of DNS retries.

SIM7080_DNS_MAX_TIMEOUT_MS

#define SIM7080_DNS_MAX_TIMEOUT_MS   60000

Maximum timeout for DNS queries in milliseconds.

SIM7080_GNSS_DATA_UTC_LEN

#define SIM7080_GNSS_DATA_UTC_LEN   20

Maximum Length of GNSS UTC data.

SIM7080_SMS_MAX_LEN

#define SIM7080_SMS_MAX_LEN   160

Maximum SMS length.

SIM7080_UE_SYS_INFO_BAND_SIZE

#define SIM7080_UE_SYS_INFO_BAND_SIZE   32

Maximum UE system information band size.

Enumeration Type Documentation

sim7080_ftp_rc

enum sim7080_ftp_rc

Possible ftp return codes.

Enumerator
SIM7080_FTP_RC_OK	Operation finished correctly.
SIM7080_FTP_RC_FINISHED	Session finished.
SIM7080_FTP_RC_ERROR	An error occurred.

sim7080_sms_stat

enum sim7080_sms_stat

Possible sms states in memory.

Enumerator
SIM7080_SMS_STAT_REC_UNREAD	Message unread.
SIM7080_SMS_STAT_REC_READ	Message read.
SIM7080_SMS_STAT_STO_UNSENT	Message stored unsent.
SIM7080_SMS_STAT_STO_SENT	Message stored sent.
SIM7080_SMS_STAT_ALL	Status count.

sim7080_state

enum sim7080_state

Sim7080 modem state.

Enumerator
SIM7080_STATE_INIT	Initial modem state.
SIM7080_STATE_IDLE	Modem idle.
SIM7080_STATE_NETWORKING	Network active.
SIM7080_STATE_GNSS	GNSS active.
SIM7080_STATE_OFF	Modem off.

sim7080_ue_op_mode

enum sim7080_ue_op_mode

UE operating mode.

Enumerator
SIM7080_UE_OP_MODE_ONLINE	Online.
SIM7080_UE_OP_MODE_OFFLINE	Offline.
SIM7080_UE_OP_MODE_FACTORY_TEST_MODE	Factory test mode.
SIM7080_UE_OP_MODE_RESET	Reset.
SIM7080_UE_OP_MODE_LOW_POWER_MODE	Low power mode.

sim7080_ue_sys_mode

enum sim7080_ue_sys_mode

UE system mode.

Enumerator
SIM7080_UE_SYS_MODE_NO_SERVICE	No service.
SIM7080_UE_SYS_MODE_GSM	GSM.
SIM7080_UE_SYS_MODE_LTE_CAT_M1	LTE CAT M1.
SIM7080_UE_SYS_MODE_LTE_NB_IOT	LTE NB IOT.

Function Documentation

mdm_sim7080_delete_sms()

int mdm_sim7080_delete_sms

(

uint16_t

index

)

Delete a sms at a given index.

Parameters

index

The index of the sms in memory.

Returns

0 on success. Otherwise -1 is returned.

mdm_sim7080_dns_get_lookup_params()

void mdm_sim7080_dns_get_lookup_params	(	uint8_t *	recount,
		uint16_t *	timeout )

Get the dns query lookup parameters.

Parameters

recount	[out] Number of retries per query.
timeout	[out] Timeout for a dns query in milliseconds.

mdm_sim7080_dns_set_lookup_params()

int mdm_sim7080_dns_set_lookup_params	(	uint8_t	recount,
		uint16_t	timeout )

Set the dns query lookup parameters.

Parameters

recount	Number of retries per query. Maximum SIM7080_DNS_MAX_RECOUNT
timeout	Timeout for a dns query in milliseconds. Maximum SIM7080_DNS_MAX_TIMEOUT_MS

Returns

0 on success. Otherwise a negative error is returned.

mdm_sim7080_download_xtra()

int mdm_sim7080_download_xtra	(	uint8_t	server_id,
		const char *	f_name )

Download the XTRA file for assisted gnss.

Parameters

server_id	Id of the server to download XTRA file from.
f_name	The name of the XTRA file to download.

Returns

0 on success. Otherwise <0 is returned.

mdm_sim7080_force_reset()

void mdm_sim7080_force_reset

(

void

)

Forcefully reset the modem by pulling pwrkey for 15 seconds.

Note

The state of the modem may be undefined after calling this function. Call mdm_sim7080_power_on after force reset.

mdm_sim7080_ftp_get_read()

int mdm_sim7080_ftp_get_read	(	char *	dst,
		size_t *	size )

Read data from a ftp get session.

Parameters

dst	The destination buffer.
size	Initialize to the size of dst. Gets set to the number of bytes actually read.

Returns

According sim7080_ftp_rc.

mdm_sim7080_ftp_get_start()

int mdm_sim7080_ftp_get_start	(	const char *	server,
		const char *	user,
		const char *	passwd,
		const char *	file,
		const char *	path )

Start a ftp get session.

Parameters

server	The ftp servers address.
user	User name for the ftp server.
passwd	Password for the ftp user.
file	File to be downloaded.
path	Path to the file on the server.

Returns

0 if the session was started. Otherwise -1 is returned.

mdm_sim7080_get_battery_charge()

int mdm_sim7080_get_battery_charge	(	uint8_t *	bcs,
		uint8_t *	bcl,
		uint16_t *	voltage )

Read voltage, charge status and battery connection level.

Parameters

bcs	[out] Charge status.
bcl	[out] Battery connection level.
voltage	[out] Battery voltage in mV.

Returns

0 on success. Otherwise a negative error is returned.

mdm_sim7080_get_iccid()

const char * mdm_sim7080_get_iccid

(

void

)

Get the sim7080 iccid number.

mdm_sim7080_get_imei()

const char * mdm_sim7080_get_imei

(

void

)

Get the sim7080 imei number.

mdm_sim7080_get_local_time()

int mdm_sim7080_get_local_time

(

struct tm *

t

)

Get the local time of the modem.

Parameters

t	Time structure to fill.

Returns

0 on success. Otherwise a negative error is returned.

Note

Time is set by network. It may take some time for it to get valid.

mdm_sim7080_get_manufacturer()

const char * mdm_sim7080_get_manufacturer

(

void

)

Get the sim7080 manufacturer.

mdm_sim7080_get_model()

const char * mdm_sim7080_get_model

(

void

)

Get the sim7080 model information.

mdm_sim7080_get_revision()

const char * mdm_sim7080_get_revision

(

void

)

Get the sim7080 revision.

mdm_sim7080_get_state()

enum sim7080_state mdm_sim7080_get_state

(

void

)

Get the current state of the modem.

Returns

The current state.

mdm_sim7080_get_ue_sys_info()

int mdm_sim7080_get_ue_sys_info

(

struct sim7080_ue_sys_info *

info

)

Read the ue system information.

Parameters

info	Destination buffer for information.

Returns

0 on success. Otherwise a negative error is returned.

mdm_sim7080_power_off()

int mdm_sim7080_power_off

(

void

)

Power off the Sim7080.

Returns

0 on success. Otherwise -1 is returned.

mdm_sim7080_power_on()

int mdm_sim7080_power_on

(

void

)

Power on the Sim7080.

Returns

0 on success. Otherwise -1 is returned.

mdm_sim7080_query_gnss()

int mdm_sim7080_query_gnss

(

struct sim7080_gnss_data *

data

)

Query gnss position form the modem.

Returns

0 on success. If no fix is acquired yet -EAGAIN is returned. Otherwise <0 is returned.

mdm_sim7080_query_xtra_validity()

int mdm_sim7080_query_xtra_validity	(	int16_t *	diff_h,
		int16_t *	duration_h,
		struct tm *	inject )

Query the validity of the XTRA file.

Parameters

diff_h	Difference between the local time and the XTRA inject time in hours.
duration_h	Valid time of the XTRA file in hours.
inject	Injection time of the XTRA file.

mdm_sim7080_read_sms()

int mdm_sim7080_read_sms

(

struct sim7080_sms_buffer *

buffer

)

Read sms from sim module.

Parameters

buffer

Buffer structure for sms.

Returns

Number of sms read on success. Otherwise -1 is returned.

Note

The buffer structure needs to be initialized to the size of the sms buffer. When this function finishes successful, nsms will be set to the number of sms read. If the whole structure is filled a subsequent read may be needed.

mdm_sim7080_set_gpio()

int mdm_sim7080_set_gpio	(	int	gpio,
		int	level )

Set the level of one of the module's GPIO pins.

Parameters

gpio	GPIO pin number
level	New logical level of the GPIO

Returns

0 on success. Otherwise -1 is returned.

Note

The GPIO will be configured as output implicitly.

mdm_sim7080_start_gnss()

int mdm_sim7080_start_gnss

(

void

)

Starts the modem in gnss operation mode.

Returns

0 on success. Otherwise <0 is returned.

Note

The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.

mdm_sim7080_start_gnss_xtra()

int mdm_sim7080_start_gnss_xtra

(

void

)

Starts the modem in gnss operation mode with xtra functionality.

Returns

0 on success. Otherwise <0 is returned.

Note

The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.

If enabling xtra functionality fails a normal cold start will be performed.

mdm_sim7080_start_network()

int mdm_sim7080_start_network

(

void

)

Activates the network operation mode of the modem.

Returns

0 on success. Otherwise <0 is returned.

Note

The modem needs to be booted for this function to work. Concurrent use of network and gnss is not possible.

mdm_sim7080_stop_gnss()

int mdm_sim7080_stop_gnss

(

void

)

Stops the modem gnss operation mode.

Returns

0 on success. Otherwise <0 is returned.

mdm_sim7080_stop_network()

int mdm_sim7080_stop_network

(

void

)

Stops the networking operation mode of the modem.

Returns

0 on success. Otherwise <0 is returned.