TiLDA MK4/sim800

From EMF Badge
Revision as of 16:09, 29 August 2018 by Alistair (talk | contribs) (Advanced functions added.)
Jump to navigation Jump to search


Overview

Calling

Call

sim800.call(number)

number = Number to call. This can be an integer but you will need ti use a string if your number has a "0" prefix

Answer Call

sim800.answer()

End/Reject Call

sim800.hangup()

Redial

sim800.redial()

Incoming Call Number

sim800.latestnumber()

Returns the number of the current caller if ringing. Returns the number of the last caller if not ringing.

Ringing

sim800.isringing()

Returns True if ringing.

The sim800.getstatus() also returns 2 when ringing and machine.Pin(machine.Pin.GPIO_SIM_RI, machine.Pin.IN).value() will show the start of the hardware ringer indicator pin. You an also user a callback (documented below) with the call name of "RING".

Play DTMF

sim800.dtmf(number)

Plays DTMF tones on an active call.

number: The number of the tone to play. This can a string of numbers that are played in sequence. Using "," will pause for one second. (int or str)

SMS

List SMS Messages

sim800.listsms([stat])

List available SMS messages.

stat:

0 = received unread messages (default)
1 = Received read messages
2 = Stored unsent messages
3 = Stored sent messages
4 = All message

File System

The SIM800 module has around 90KB of file storage. This can be used to store files to send to or receive from and paired Bluetooth device as well as for audio recordings.

Free Space

sim800.fsfree()

Returns the number of bytes available in the file system.

List Directory

sim800.fsls([directory])

directory: The directory on the file system relative to root to list. Directories end with a backslash. The root directory is returned if no parameter is given.

A list of file names is returned. Directories end with a "\". Don't forget to escape this as "\\" in your code.

File Size

sim800.fssize(filename)

filename: The directory and filename of the file.

The size of the file in bytes. A size of -1 is returned if the file does not exist.

Create Directory

sim800.fsmkdir(directory)

Creates a directory.

directory: The name of the directory to create.

Remove Directory

Removes a directory.

sim800.fsrmdir(directory)

directory: The name of the directory to delete.

Create a file

sim800.fscreate(filename)

Creates an empty file.

filename: The filename of the file (including directory) to create.

Read From File

sim800.fsread(filename)

Returns the contents of the file.

filename: The filename of the file (including directory) to read.

Note that this can be slow. You may want to use sim800.uartspeed(460800) to speed things up but you are advised to call sim800.uartspeed(0) after to switch back to automatic.

Write To File

sim800.fswrite(filename, data, [truncate])

filename: The filename of the file (including directory) to read. data: The data to write to the file truncate: If True the original file emptied first. If False data is appended to the end of the file. Defaults to False.

Note that this can be slow. You may want to use sim800.uartspeed(460800) to speed things up but you are advised to call sim800.uartspeed(0) after to switch back to automatic.

Delete File

sim800.fsrm(filename)

filename: The filename of the file to delete.

Rename File

sim800.fsmv(from, to)

Rename a file.

from: The old filename. To: The new filename.

Bluetooth

sim800.


Network and Status

Callbacks

Register for a Callback

sim800.call(call, function)

You can register a function that is called when a response is sent by the SIM800. This allows you to detect calls, incoming messages, Bluetooth requests and other advanced responses.

call: The response call to be watched for function: The function to be called.

The function must take one string parameter. This parameter contains the the parameters sent from the SIM800. You pass the function by it's name without the training brackets.

Some example calls are;

  • "RING" - Triggered when an incoming call is detected.
  • "+CLIP:" - When caller line identification is received (ie the caller's number).
  • "+CMT:" - A new SMS message is received.
  • "+DTMF:" - A DTMF tone is detected.
  • "+BTPAIRING:" - A Bluetooth paring request.

For "RING" the parameter will always be an empty string but your function must accept it. When this is triggered the library the callers number may not be valid and "+CLIP:" should be used instead.

Take care not to change things the active app will be using such as the string. This call will be in the same thread but may happen in the middle of another function. If odd things start happening with anything on the badge then try disabling your callbacks is a good thing to try.

Deregister from a Callback

sim800.deregistercallback(function)

function: The function that was used when registering for the callback.

Custom SIM800 Command Calls

sim800.command([command], [response_timeout], [required_response], [custom_endofdata])

command: The AT command to send. A full set of of these commands are available in the SIMCom documentation. Links to the most useful ones are below. response_timeout: The time to wait for a response in milliseconds. required_response: The start of a response we will keep waiting for. If not found in time we will receive a "TIMEOUT" custom_endofdata: The start of a response we want for data sent after an "OK" or "ERROR" response.

This returns an array that should start with an echo of the command sent and normally ends with a response identifying if the call was successful. If a required_response or custom_endofdata is specified then this will be the last line. If such a response has not been received before the timeout a response of "TIMEOUT" is sent.

As other apps may be monitoring the SIM800 for data relevant to them. Please do not access the UART directly unless you really have to. If you want to receive then use the callback above and call sim800.processbuffer() to process the incoming data. If you really have to then you can access the UART directly via sim800.uart.

Further details about the AT commands can be found in the following documents.

There are also some helper functions that you might find useful.

sim800.sim800.ispositive(response)

response: The last line of data returned from sim800.command().

Returns True if it was positive such as "OK" or "CONNECTED".

sim800.isnegative(response)

response: The last line of data returned from sim800.command().

Returns True if it was negative such as "ERROR" or "NO CARRIER".

sim800.extractval(parameter, response, [default])

This looks for the first occurrence of a parameter passed back from the SIM800.

The value of the parameter is returned as a string, or the default if it is not found.

parameter: The parameter you are looking for. "+GCAP:" for example. response: The response from sim800.command() default: The value to return if the parameter is not found. Defaults to an empty string.

sim800.extractvals(parameter, response)

This looks for the occurrences of a parameter passed back from the SIM800.

An array of values of the parameters are returned.

parameter: The parameter you are looking for. "+CENG:" for example. response: The response from sim800.command()